TextAttributeRunIterator Class Reference

#include <TextAttributeRunIterator.h>

Public Member Functions
	TextAttributeRunIterator (K2Vector< InDesign::TextRange >::const_iterator firstRange, K2Vector< InDesign::TextRange >::const_iterator endOfRanges, K2Vector< ClassID >::const_iterator firstAttributeClass, K2Vector< ClassID >::const_iterator endOfAttributeClasses)
	TextAttributeRunIterator (const TextAttributeRunIterator &other)
const AttributeBossList &	operator* () const
const AttributeBossList *	operator-> () const
TextAttributeRunIterator &	operator++ ()
bool16	operator< (const TextAttributeRunIterator &other) const
	operator bool ()
ErrorCode	ApplyAttributes (const boost::shared_ptr< AttributeBossList > &attributes, const ClassID &which=kCharAttrStrandBoss)
ErrorCode	ApplyAttribute (IPMUnknown *attribute, const ClassID &which=kCharAttrStrandBoss)
RangeData	GetRunRange () const

Detailed Description

The TextAttributeRunIterator class is very handy for walking through one or more text ranges,

examining the value of one or more text attributes within the ranges and optionally applying

different attributes to the ranges.



Here's a simple example for increasing the point size of text by "incrementAmt" relative to whatever

size it was to begin with.  Note that this works when the selection contains mixed point sizes since

the iterator "walks" to each range of text that has one consistent set of values for the given attributes.

(In this case each span of text that has the same point size with in the given set of ranges.)



    K2Vector<ClassID> attributeClasses;

    attributeClasses.reserve(1);

    attributeClasses.push_back(kTextAttrPointSizeBoss);



    TextAttributeRunIterator runIter(textRanges.begin(), textRanges.end(), attributeClasses.begin(), attributeClasses.end());



    while (runIter)

        {

At this point the only attribute in the AttributeBossList at *runIter is a kTextAttrPointSizeBoss. If the iterator had been constructed with more than one attribute in the attributeClasses vector, then QueryByClassID would be used to access the desired text attribute (i.e. runIter->QueryByClassID(kTextAttrPointSizeBoss, ITextAttrRealNumber::kDefaultIID)).

        InterfacePtr<const ITextAttrRealNumber> originalAttr(static_cast<const ITextAttrRealNumber *>(runIter->QueryBossN(0, ITextAttrRealNumber::kDefaultIID)));

Create a new attribute with an incremented point size. InterfacePtr<ITextAttrRealNumber> newAttr(this->CreateRealNumberAttribute(attributeClass, originalAttr->Get() + incrementAmt));

Apply the new point size to the range that had the previous point size. runIter.ApplyAttribute(newAttr);

++runIter; }

This iterator class is used extensively by the various implementations of ITextAttributeSuite to implement the increase/decrease and toggle attribute value features.

Applying attributes via the iterator doesn't invalidate the iterator. However, applying attributes outside the iterator, editing styles or performing text edits (insert/delete) do invalidate the iterator and will result in unpredicatable behavior. If you need to mix these operations with using a TextAttributeRunIterator, you should destruct and construct a new iterator after each "external" operation.

Constructor & Destructor Documentation

TextAttributeRunIterator::TextAttributeRunIterator	(	K2Vector< InDesign::TextRange >::const_iterator	firstRange,
		K2Vector< InDesign::TextRange >::const_iterator	endOfRanges,
		K2Vector< ClassID >::const_iterator	firstAttributeClass,
		K2Vector< ClassID >::const_iterator	endOfAttributeClasses
	)

Construct an interator by passing in iterators for the start and end of a range of InDesign::TextRange objects within a vector. The TextRange vector can represent multiple ranges within a single text model (i.e. table cells), multiple ranges in different text models (i.e. text frame pointer tool selection), or just a single range in a single text model. And pass the same style of begin/end iterators into a vector of the ClassIDs of the text attributes to be considered when breaking the text into runs.

Parameters

firstRange	the first TextRange of those to be iterated.
endOfRanges	the last+1th TextRange of those to be iterated.
firstAttributeClass	the first attribute ClassID of those to be considered as part of a "run".
endOfAttributeClasses	the last+1th attributes ClassID of those to be consider as part of a "run".

TextAttributeRunIterator::TextAttributeRunIterator ( const TextAttributeRunIterator &  other )

inline

Copy constructor

Member Function Documentation

ErrorCode TextAttributeRunIterator::ApplyAttribute	(	IPMUnknown *	attribute,
		const ClassID &	which = kCharAttrStrandBoss
	)

Applies a single text attributes to the range of text at the current position of the iterator.

ErrorCode TextAttributeRunIterator::ApplyAttributes	(	const boost::shared_ptr< AttributeBossList > &	attributes,
		const ClassID &	which = kCharAttrStrandBoss
	)

Applies the given set of text attributes to the range of text at the current position of the iterator.

RangeData TextAttributeRunIterator::GetRunRange ( ) const

inline

Returns the range of the current span of text at the iterator.

TextAttributeRunIterator::operator bool ( )

inline

Used to indicate when the iterator has fallen of the end of the list of ranges

const AttributeBossList& TextAttributeRunIterator::operator*

(

)

const

Returns an AttributeBossList at the current location of the iterator. WARNING: This const & is only valid as long as the iterator is in scope and is altered by advancing (operator++) the iterator. If you wish to compare the attributes of consecutive runs, you need to either use 2 iterators or be sure to make a copy of the AttributeBossList before calling operator++.

TextAttributeRunIterator& TextAttributeRunIterator::operator++

(

)

Advances the iterator to the next span of text where the list of attributes passed to the constructor all have the same values, and silently walks from each of the passed in text ranges to the next.

const AttributeBossList* TextAttributeRunIterator::operator->

(

)

const

Allows for iter-> usage to access the member functions of the AttributeBossList at the iterator location.

bool16 TextAttributeRunIterator::operator< ( const TextAttributeRunIterator &  other ) const

inline

Compare the locations of two text iterators. This is really only meaningful if the iterators are in the same text model.