Led Class Library 3.0 / ReferenceManual

Led 3.0 Class Library Documentation

Module PartitioningTextImager

Classes and Global Functions Index

Partition

Partition::PartitionMarker

Partition::PartitionWatcher

PartitioningTextImager

Module Description:

PartitioningTextImager is based on the idea that a entire text buffer can be layed out by first breaking the text into special chunks, and then laying out those chunks.

We use Markers (or more specificly Partition::PartitionMarker) to delimit the chunks (refered to as partition elements).

Note that it doesn't really matter much what the rule is for breaking text into chunks, except that the rule should be chosen to make the drawing of those chunks easier, and to fit in well with logical clipping.

So for example, the most common rule for breaking text into partitions would be to look for LF chraracters, and consider each "line" to be a separate partition element.

Class: `Partition [public]`

Base Classes: `virtual MarkerOwner`

Description:

PartitioningTextImager is a TextImager which implements imaging by partitioning the text into stable regions, called Partitions.

A partition is logically very similar to a MarkerCover. But we don't directly use that class because it is not an abstract class, but rather a utility template. And that utility has very different performance considerations than we require. Also, that class is used to associate a MARKERINFO with a particular partition element. There is nothing we here associate with the partition element.

For more information, see DesignManual/TextImagers.html (NB: This code has changed ALOT between Led 2.2 and 2.3, and so this doc really needs to be rewritten!).

Member Details

Member Details
`Partition::AccumulateMarkerForDeletion [public]` `void Partition::AccumulateMarkerForDeletion (PartitionMarker* m)` Wrap `MarkerMortuary::AccumulateMarkerForDeletion` - and make sure our cache isn't pointing to a deleted marker.
`Partition::AddPartitionWatcher [public]` `void Partition::AddPartitionWatcher (PartitionWatcher* watcher)` Associate the given `Partition::PartitionWatcher` with this Partition. Use `Partition::RemovePartitionWatcher` to remove the callback / association.
`Partition::Coalece [public]` `void Partition::Coalece (PartitionMarker* pm)` Coalece the given PartitionMarker with the one which follows it (if any exists). If coalesced with the following element, the given 'pm' is deleted. Frequently this doesn't happen immediately (mainly for performance reasons, but possibly also to avoid bugs where the marker is still in some list being iterated over and having DidUpdate() etc methods called on it). It is accumulated for later deletion using `Partition::AccumulateMarkerForDeletion`. This method is typically called by Partition subclasses override of Partition::UpdatePartitions.
`Partition::CopyOut [public]` `void Partition::CopyOut (size_t from, size_t byteCount, Led_tChar* buffer) const` Calls the associated `TextStore::CopyOut` ().
`Partition::FinalConstruct [public]` `void Partition::FinalConstruct ()` Logically this should be part of the constructor. But since it needs to call a method (Partition::MakeNewPartitionMarker ()) which is virtual, and must be bound in the final complete class. So it must be done as a separate call. It is illegal to call this more than once, or to call any of the other class methods without having called it. These errors will be detected (in debug builds) where possible.
`Partition::GetEnd [public]` `size_t Partition::GetEnd () const` Return the associated `TextStore::GetEnd` ().
`Partition::GetPartitionMarkerContainingPosition [public]` `PartitionMarker* Partition::GetPartitionMarkerContainingPosition (size_t charPosition) const` Finds the PartitioningTextImager::PartitionMarker which contains the given character#. Note, the use of 'charPosition' rather than markerpos is to disambiguiate the case where we are at the boundary between two partition elements.
`Partition::MakeNewPartitionMarker [public]` `PartitionMarker* Partition::MakeNewPartitionMarker (PartitionMarker* insertAfterMe)` Method which is called to construct new partition elements. Override this if you subclass `PartitioningTextImager`, and want to provide your own subtype of PartitioningTextImager::PartitionMarker.
`Partition::RemovePartitionWatcher [public]` `void Partition::RemovePartitionWatcher (PartitionWatcher* watcher)` Remove the given `Partition::PartitionWatcher` from being associated with this `Partition`. Balances calls from `Partition::AddPartitionWatcher`.
`Partition::Split [public]` `void Partition::Split (PartitionMarker* pm, size_t at)` Split the given PartitionMarker at position 'at' - which must fall within the partition element. This method always produces a new partition element, and inserts it appropriately into the partition, adjusting the sizes of surrounding elements appropriately. This method is typically called by Partition subclasses override of Partition::UpdatePartitions.

Partition::AccumulateMarkerForDeletion [public]

void Partition::AccumulateMarkerForDeletion (PartitionMarker* m)

Wrap MarkerMortuary::AccumulateMarkerForDeletion - and make sure our cache isn't pointing to a deleted marker.

Partition::AddPartitionWatcher [public]

void Partition::AddPartitionWatcher (PartitionWatcher* watcher)

Associate the given Partition::PartitionWatcher with this Partition. Use Partition::RemovePartitionWatcher to remove the callback / association.

Partition::Coalece [public]

void Partition::Coalece (PartitionMarker* pm)

Coalece the given PartitionMarker with the one which follows it (if any exists). If coalesced with the following element, the given 'pm' is deleted. Frequently this doesn't happen immediately (mainly for performance reasons, but possibly also to avoid bugs where the marker is still in some list being iterated over and having DidUpdate() etc methods called on it). It is accumulated for later deletion using Partition::AccumulateMarkerForDeletion.

This method is typically called by Partition subclasses override of Partition::UpdatePartitions.

Partition::CopyOut [public]

void Partition::CopyOut (size_t from, size_t byteCount, Led_tChar* buffer) const

Calls the associated TextStore::CopyOut ().

Partition::FinalConstruct [public]

void Partition::FinalConstruct ()

Logically this should be part of the constructor. But since it needs to call a method (Partition::MakeNewPartitionMarker ()) which is virtual, and must be bound in the final complete class. So it must be done as a separate call. It is illegal to call this more than once, or to call any of the other class methods without having called it. These errors will be detected (in debug builds) where possible.

Partition::GetEnd [public]

size_t Partition::GetEnd () const

Return the associated TextStore::GetEnd ().

Partition::GetPartitionMarkerContainingPosition [public]

PartitionMarker* Partition::GetPartitionMarkerContainingPosition (size_t charPosition) const

Finds the PartitioningTextImager::PartitionMarker which contains the given character#. Note, the use of 'charPosition' rather than markerpos is to disambiguiate the case where we are at the boundary between two partition elements.

Partition::MakeNewPartitionMarker [public]

PartitionMarker* Partition::MakeNewPartitionMarker (PartitionMarker* insertAfterMe)

Method which is called to construct new partition elements. Override this if you subclass PartitioningTextImager, and want to provide your own subtype of PartitioningTextImager::PartitionMarker.

Partition::RemovePartitionWatcher [public]

void Partition::RemovePartitionWatcher (PartitionWatcher* watcher)

Remove the given Partition::PartitionWatcher from being associated with this Partition. Balances calls from Partition::AddPartitionWatcher.

Partition::Split [public]

void Partition::Split (PartitionMarker* pm, size_t at)

Split the given PartitionMarker at position 'at' - which must fall within the partition element. This method always produces a new partition element, and inserts it appropriately into the partition, adjusting the sizes of surrounding elements appropriately.

This method is typically called by Partition subclasses override of Partition::UpdatePartitions.

Class: `Partition::PartitionMarker [public]`

Base Classes: `Marker`

Description:

This class is the building block of a partition. It is used to keep track of a single partition element.

Subclassing Caution: Since we provide operator new/delete overrides, you must be careful building any subclasses which have a different size than this class. You must provide your own overrides of operator new/delete todo so.

Member Details

Member Details
`Partition::PartitionMarker::GetOwner () [public]` `Partition& Partition::PartitionMarker::GetOwner () const` Return a reference to the partition markers owner. Note - since this returns a refernece, we assert that the owner is non-null. Also note that this routine intentionally hides the base-class Marker::GetOwner() method. Use that if the owner could be NULL. But note that the owner will never be NULL if the marker has been added (and not yet removed) from the TextStore.

Partition::PartitionMarker::GetOwner () [public]

Partition& Partition::PartitionMarker::GetOwner () const

Return a reference to the partition markers owner. Note - since this returns a refernece, we assert that the owner is non-null. Also note that this routine intentionally hides the base-class Marker::GetOwner() method. Use that if the owner could be NULL. But note that the owner will never be NULL if the marker has been added (and not yet removed) from the TextStore.

Class: `Partition::PartitionWatcher [public]`

Description:

Some programs may need to keep track of when a partition changes. For example, an Imager will likely want to redisplay itself. Perhaps even do some more elaborate computation. Things like paragraph-based marker-covers (MarkerCover) may need to adjust their boundaries to correspond to the new paragraph boundaries (e.g. WordProcessor::ParagraphDatabaseRep).

You get notified just before, and after partition markers are split, and/or coalesced. The untyped 'info' records are used to pass arbitrary bits of info from the 'about' call to the 'did' call.

Class: `PartitioningTextImager [public]`

Base Classes: `virtual TextImager`

Description:

PartitioningTextImager is a TextImager which implements imaging by partitioning the text into stable regions, called Partitions.

For more information, see DesignManual/TextImagers.html.

Member Details

Member Details
`PartitioningTextImager::CalcSegmentSizeWithImmediateText [public]` `Led_Distance PartitioningTextImager::CalcSegmentSizeWithImmediateText (size_t from, size_t to, const Led_tChar* text) const` This is typically called from PartitioningTextImager::CalcSegmentSize, which first grabs the text from the buffer, and then measures the text width. And it does the same thing, except that this routine is optimized so it doesn't lookup the text, and requires you to pass it in (avoids extra copying out of text from `TextStore`). This routine was renamed from and overloaded PartitioningTextImager::CalcSegmentSize between Led 2.2 and Led 2.3.
`PartitioningTextImager::GetEndOfPartitionContainingPosition [public]` `size_t PartitioningTextImager::GetEndOfPartitionContainingPosition (size_t charPosition) const` Simple wrapper on `PartitioningTextImager::GetPartitionMarkerContainingPosition`. Returns marker position AFTER end of partition (same as START position of following partition - if any).
`PartitioningTextImager::GetPartitionMarkerContainingPosition [public]` `Partition::PartitionMarker* PartitioningTextImager::GetPartitionMarkerContainingPosition (size_t charPosition) const` Finds the PartitioningTextImager::PartitionMarker which contains the given character#. Note, the use of 'charPosition' rather than markerpos is to disambiguiate the case where we are at the boundary between two partition elements.
`PartitioningTextImager::GetStartOfPartitionContainingPosition [public]` `size_t PartitioningTextImager::GetStartOfPartitionContainingPosition (size_t charPosition) const` Simple wrapper on `PartitioningTextImager::GetPartitionMarkerContainingPosition`.
`PartitioningTextImager::ResetTabStops [public]` `size_t PartitioningTextImager::ResetTabStops (size_t from, const Led_tChar* text, size_t nTChars, Led_Distance* charLocations, size_t startSoFar) const` Patch the charLocations for tab-stop locations, now that we know our previous wrap point. Returns index of last tab found (allows for optimizations). Returns a number <= from if no tabs found. 'from' defines where in the 'textStore' all these things are being measured relative to (typically the start of a partition). 'text' is the text starting in the partition at position 'from', and extending 'nTChars' Led_tChars in length. 'charLocations' is a vector - of the widths, measured from TextImager::MeasureSegmentWidth. As such, it measures distances from 'from' to a position 'i' after from, with the distance of from..from being implied zero, so the first elt of the array left out (in other words to find distance from..i, you say charLocations[i-from-1]). 'startSoFar' is an arg so you can only reset the tabstops for a given subset of the text - ignoring the initial portion. So, if startSoFar==0, then it is assumed we are starting at the beginning of the charLocations array, but if startSoFar != 0, we assume we can (and must) snag our starting width from what is already in the array at charLocations[startSoFar-1].
`PartitioningTextImager::SetPartition [public]` `void PartitioningTextImager::SetPartition (const PartitionPtr& partitionPtr)` Associates the given parition (PartitionPtr) with this `PartitioningTextImager`. It can be NULL. The method is virtual, in case you need to hook partition changes by updating other derived/cached information. But if overridding, be sure to always call the inherited version.

PartitioningTextImager::CalcSegmentSizeWithImmediateText [public]

Led_Distance PartitioningTextImager::CalcSegmentSizeWithImmediateText (size_t from, size_t to, const Led_tChar* text) const

This is typically called from PartitioningTextImager::CalcSegmentSize, which first grabs the text from the buffer, and then measures the text width. And it does the same thing, except that this routine is optimized so it doesn't lookup the text, and requires you to pass it in (avoids extra copying out of text from TextStore).

This routine was renamed from and overloaded PartitioningTextImager::CalcSegmentSize between Led 2.2 and Led 2.3.

PartitioningTextImager::GetEndOfPartitionContainingPosition [public]

size_t PartitioningTextImager::GetEndOfPartitionContainingPosition (size_t charPosition) const

Simple wrapper on PartitioningTextImager::GetPartitionMarkerContainingPosition. Returns marker position AFTER end of partition (same as START position of following partition - if any).

PartitioningTextImager::GetPartitionMarkerContainingPosition [public]

Partition::PartitionMarker* PartitioningTextImager::GetPartitionMarkerContainingPosition (size_t charPosition) const

PartitioningTextImager::GetStartOfPartitionContainingPosition [public]

size_t PartitioningTextImager::GetStartOfPartitionContainingPosition (size_t charPosition) const

Simple wrapper on PartitioningTextImager::GetPartitionMarkerContainingPosition.

PartitioningTextImager::ResetTabStops [public]

size_t PartitioningTextImager::ResetTabStops (size_t from, const Led_tChar* text, size_t nTChars, Led_Distance* charLocations, size_t startSoFar) const

Patch the charLocations for tab-stop locations, now that we know our previous wrap point. Returns index of last tab found (allows for optimizations). Returns a number <= from if no tabs found.

'from' defines where in the 'textStore' all these things are being measured relative to (typically the start of a partition).

'text' is the text starting in the partition at position 'from', and extending 'nTChars' Led_tChars in length.

'charLocations' is a vector - of the widths, measured from TextImager::MeasureSegmentWidth. As such, it measures distances from 'from' to a position 'i' after from, with the distance of from..from being implied zero, so the first elt of the array left out (in other words to find distance from..i, you say charLocations[i-from-1]).

'startSoFar' is an arg so you can only reset the tabstops for a given subset of the text - ignoring the initial portion. So, if startSoFar==0, then it is assumed we are starting at the beginning of the charLocations array, but if startSoFar != 0, we assume we can (and must) snag our starting width from what is already in the array at charLocations[startSoFar-1].

PartitioningTextImager::SetPartition [public]

void PartitioningTextImager::SetPartition (const PartitionPtr& partitionPtr)

Associates the given parition (PartitionPtr) with this PartitioningTextImager. It can be NULL.

The method is virtual, in case you need to hook partition changes by updating other derived/cached information. But if overridding, be sure to always call the inherited version.