ATE::ITextRanges Class Reference

Encapsulates a set of text ranges. More...

#include <IText.h>

List of all members.

Public Member Functions
	ITextRanges ()
	Constructor.
	ITextRanges (const ITextRanges &src)
	Copy constructor.
ITextRanges &	operator= (const ITextRanges &rhs)
	Assignment operator.
bool	operator== (const ITextRanges &rhs) const
	Comparison operator tests for equality.
bool	operator!= (const ITextRanges &rhs) const
	Comparison operator tests for inequality.
	ITextRanges (TextRangesRef textranges)
	Constructs this C++ object from the corresponding C object returned by an ATE suite function.
virtual	~ITextRanges ()
	Destructor.
TextRangesRef	GetRef () const
	Retrieves a reference to this object.
bool	IsNull () const
	Reports whether this is a null object.
ATETextDOM::Int32	GetSize () const
	Retrieves the number of members of this set.
ITextRange	GetFirst () const
	Retrieves the first member of this set.
ITextRange	GetLast () const
	Retrieves the last member of this set.
ITextRanges	GetTextSelection () const
	Retrieves the selected text within this text range set.
IParagraphsIterator	GetParagraphsIterator () const
	Creates an iterator for the paragraphs contained in this text range set.
IWordsIterator	GetWordsIterator () const
	Creates an iterator for the words contained in this text range set.
ITextRunsIterator	GetTextRunsIterator () const
	Creates an iterator for the text runs contained in this text range set.
ICharInspector	GetCharInspector () const
	Creates an inspector with which to access the character features of all characters in this text range set.
IParaInspector	GetParaInspector () const
	Creates an inspector with which to access the paragraph features of all paragraphs in this text range set.
void	ClearNamedCharStyle ()
	Removes the association of this text range set and its character style.
void	ClearNamedParaStyle ()
	Removes the association of this text range set and its paragraph style.
ICharFeatures	GetUniqueCharFeatures () const
	Retrieves the unique character features used in this text range set.
IParaFeatures	GetUniqueParaFeatures () const
	Retrieves the unique paragraph features used in this text range set.
bool	HasLocalCharFeatures ()
	Reports whether there any local character feature overrides for characters contained in this text range set.
bool	HasLocalParaFeatures ()
	Reports whether there any local paragraph feature overrides for paragraphs contained in this text range set.
ICharFeatures	GetUniqueLocalCharFeatures ()
	Retrieves the character features that have local overrides in this text range set, and whose local values are the same in all text runs in the ranges.
IParaFeatures	GetUniqueLocalParaFeatures ()
	Retrieves the paragraph features that have local overrides in this text range set, and whose local values are the same in all text runs in the ranges.
void	SetLocalCharFeatures (const ICharFeatures &pFeatures)
	Replaces all of the local overrides for all characters in this text range set with a new set of feature values.
void	ReplaceOrAddLocalCharFeatures (const ICharFeatures &pFeatures)
	Modifies the local overrides for all characters in this text range set.
void	ClearLocalCharFeatures ()
	Removes all local overrides for all characters in this text range set.
void	SetLocalParaFeatures (const IParaFeatures &pFeatures)
	Replaces all of the local overrides for all paragraphs in this text range set with a new set of feature values.
void	ReplaceOrAddLocalParaFeatures (const IParaFeatures &pFeatures)
	Modifies the local overrides for all paragraphs in this text range set.
void	ClearLocalParaFeatures ()
	Removes all local overrides for all paragraphs in this text range set.
void	Select (bool addToSelection=false)
	Selects the text in this text range set.
void	DeSelect ()
	Deselects the text in this text range set.
ATETextDOM::Int32	GetContents (ATETextDOM::Unicode *text, ATETextDOM::Int32 maxLength) const
	Retrieves the contents of this text range set as a Unicode string.
ATETextDOM::Int32	GetContents (char *text, ATETextDOM::Int32 maxLength) const
	Retrieves the contents of this text range set as a C string.
void	ChangeCase (CaseChangeType caseChangeType)
	Changes the case of the text in this text range set.
void	Add (const ITextRange &textRange)
	Adds a text range as a member of this set.
ITextRange	Item (ATETextDOM::Int32 nIndex) const
	Retrieves a member of this set by position index.
void	RemoveAll ()
	Removes all members from the set.
void	Remove (ATETextDOM::Int32 nIndex)
	Removes a member from the set.

---

Detailed Description

Encapsulates a set of text ranges.

Contains a collection of ITextRange objects. Allows you to perform many of the text operations on all of the member ranges at once. Use an ITextRangesIterator object to iterate through the member ranges.

---

Constructor & Destructor Documentation

ATE::ITextRanges::ITextRanges

(

)

Constructor.

Returns:

The new object.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

Referenced by GetTextSelection().

ATE::ITextRanges::ITextRanges

(

const ITextRanges &

src

)

Copy constructor.

Parameters:

src

The object to copy.

Returns:

The new object.

References ATE::sTextRanges.

ATE::ITextRanges::ITextRanges

(

TextRangesRef

textranges

)

[explicit]

Constructs this C++ object from the corresponding C object returned by an ATE suite function.

The C++ object manages reference counting.

Parameters:

textranges

The C object.

Returns:

The new C++ object.

ATE::ITextRanges::~ITextRanges

(

)

[virtual]

Destructor.

References ATE::sTextRanges.

---

Member Function Documentation

void ATE::ITextRanges::Add

(

const ITextRange &

textRange

)

Adds a text range as a member of this set.

Parameters:

textRange

The text range object.

Returns:

Nothing.

References ATE::ITextRange::GetRef(), ATE::sTextRanges, and ATE::Throw_ATE_Exception().

void ATE::ITextRanges::ChangeCase

(

CaseChangeType

caseChangeType

)

Changes the case of the text in this text range set.

Parameters:

caseChangeType

The case type constant.

Returns:

Nothing.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

void ATE::ITextRanges::ClearLocalCharFeatures

(

)

Removes all local overrides for all characters in this text range set.

All character features are then inherited from styles associated with the character or text range, or from the Normal style.

Returns:

Nothing.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

void ATE::ITextRanges::ClearLocalParaFeatures

(

)

Removes all local overrides for all paragraphs in this text range set.

All paragraph features are then inherited from styles associated with the paragraph or text range, or from the Normal style.

Returns:

Nothing.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

void ATE::ITextRanges::ClearNamedCharStyle

(

)

Removes the association of this text range set and its character style.

Copies the feature values of the character style into local override values in the contained characters. See ICharFeatures.

Returns:

Nothing.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

void ATE::ITextRanges::ClearNamedParaStyle

(

)

Removes the association of this text range set and its paragraph style.

Copies the feature values of the paragraph style into local override values in the contained paragraphs. See IParaFeatures.

Returns:

Nothing.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

void ATE::ITextRanges::DeSelect

(

)

Deselects the text in this text range set.

This can result in a discontiguous selection, if this text is a subset of the selected text.

Returns:

Nothing.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

ICharInspector ATE::ITextRanges::GetCharInspector

(

)

const

Creates an inspector with which to access the character features of all characters in this text range set.

Returns:

The inspector object.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

ATETextDOM::Int32 ATE::ITextRanges::GetContents	(	char *	text,
		ATETextDOM::Int32	maxLength
	)			const

Retrieves the contents of this text range set as a C string.

Parameters:

	text	[out] A buffer in which to return the string.
	maxLength	The number of characters in the buffer.

Returns:

The number of characters in the returned string.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

ATETextDOM::Int32 ATE::ITextRanges::GetContents	(	ATETextDOM::Unicode *	text,
		ATETextDOM::Int32	maxLength
	)			const

Retrieves the contents of this text range set as a Unicode string.

Parameters:

	text	[out] A buffer in which to return the string.
	maxLength	The number of characters in the buffer.

Returns:

The number of characters in the returned string.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

ITextRange ATE::ITextRanges::GetFirst

(

)

const

Retrieves the first member of this set.

Returns:

The member object.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

ITextRange ATE::ITextRanges::GetLast

(

)

const

Retrieves the last member of this set.

Returns:

The member object.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

IParagraphsIterator ATE::ITextRanges::GetParagraphsIterator

(

)

const

Creates an iterator for the paragraphs contained in this text range set.

Returns:

The iterator object.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

IParaInspector ATE::ITextRanges::GetParaInspector

(

)

const

Creates an inspector with which to access the paragraph features of all paragraphs in this text range set.

Returns:

The inspector object.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

TextRangesRef ATE::ITextRanges::GetRef

(

)

const

Retrieves a reference to this object.

Returns:

The object reference.

Referenced by ATE::IParagraphsIterator::IParagraphsIterator(), ATE::ITextRangesIterator::ITextRangesIterator(), ATE::ITextRunsIterator::ITextRunsIterator(), and ATE::IWordsIterator::IWordsIterator().

ATETextDOM::Int32 ATE::ITextRanges::GetSize

(

)

const

Retrieves the number of members of this set.

Returns:

The number of members.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

ITextRunsIterator ATE::ITextRanges::GetTextRunsIterator

(

)

const

Creates an iterator for the text runs contained in this text range set.

Returns:

The iterator object.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

ITextRanges ATE::ITextRanges::GetTextSelection

(

)

const

Retrieves the selected text within this text range set.

Returns:

The text ranges object containing the selected text.

References ITextRanges(), ATE::sTextRanges, and ATE::Throw_ATE_Exception().

ICharFeatures ATE::ITextRanges::GetUniqueCharFeatures

(

)

const

Retrieves the unique character features used in this text range set.

Unique features are those which have the same value in all text runs in the ranges.

Returns:

The character features object containing the unique feature values. Other features are unassigned.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

ICharFeatures ATE::ITextRanges::GetUniqueLocalCharFeatures

(

)

Retrieves the character features that have local overrides in this text range set, and whose local values are the same in all text runs in the ranges.

Returns:

The character features object containing the unique local feature values. Other features are unassigned. If all features are unassigned, either there are no local overrides, or the local overrides have no common values.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

IParaFeatures ATE::ITextRanges::GetUniqueLocalParaFeatures

(

)

Retrieves the paragraph features that have local overrides in this text range set, and whose local values are the same in all text runs in the ranges.

Returns:

The paragraph features object containing the unique local feature values. Other features are unassigned. If all features are unassigned, either there are no local overrides, or the local overrides have no common values.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

IParaFeatures ATE::ITextRanges::GetUniqueParaFeatures

(

)

const

Retrieves the unique paragraph features used in this text range set.

Unique features are those which have the same value in all text runs in the ranges.

Returns:

The paragraph features object containing the unique feature values. Other features are unassigned.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

IWordsIterator ATE::ITextRanges::GetWordsIterator

(

)

const

Creates an iterator for the words contained in this text range set.

Returns:

The iterator object.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

bool ATE::ITextRanges::HasLocalCharFeatures

(

)

Reports whether there any local character feature overrides for characters contained in this text range set.

Returns:

True if there are local overrides.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

bool ATE::ITextRanges::HasLocalParaFeatures

(

)

Reports whether there any local paragraph feature overrides for paragraphs contained in this text range set.

Returns:

True if there are local overrides.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

bool ATE::ITextRanges::IsNull

(

)

const

Reports whether this is a null object.

Returns:

True if this is a null object.

References ATE::sTextRanges.

ITextRange ATE::ITextRanges::Item

(

ATETextDOM::Int32

nIndex

)

const

Retrieves a member of this set by position index.

Use with GetSize() to iterate through members.

Parameters:

nIndex

The 0-based position index.

Returns:

The member object.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

bool ATE::ITextRanges::operator!=

(

const ITextRanges &

rhs

)

const

Comparison operator tests for inequality.

Parameters:

rhs

The object to compare to this one.

Returns:

True if the two objects are not the same.

ITextRanges & ATE::ITextRanges::operator=

(

const ITextRanges &

rhs

)

Assignment operator.

Parameters:

rhs

The object to assign to this one.

Returns:

A reference to this object.

References ATE::sTextRanges.

bool ATE::ITextRanges::operator==

(

const ITextRanges &

rhs

)

const

Comparison operator tests for equality.

Parameters:

rhs

The object to compare to this one.

Returns:

True if the two objects are the same.

void ATE::ITextRanges::Remove

(

ATETextDOM::Int32

nIndex

)

Removes a member from the set.

Parameters:

nIndex

The 0-based position index of the member to remove.

Returns:

Nothing.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

void ATE::ITextRanges::RemoveAll

(

)

Removes all members from the set.

Returns:

Nothing.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

void ATE::ITextRanges::ReplaceOrAddLocalCharFeatures

(

const ICharFeatures &

pFeatures

)

Modifies the local overrides for all characters in this text range set.

All values that are assigned become local values, replacing any previous local value. Values that are unassigned leave any previous local values unchanged.

Parameters:

pFeatures

The new feature set object.

Returns:

Nothing.

References ATE::ICharFeatures::GetRef(), ATE::sTextRanges, and ATE::Throw_ATE_Exception().

void ATE::ITextRanges::ReplaceOrAddLocalParaFeatures

(

const IParaFeatures &

pFeatures

)

Modifies the local overrides for all paragraphs in this text range set.

All values that are assigned become local values, replacing any previous local value. Values that are unassigned leave any previous local values unchanged.

Parameters:

pFeatures

The new feature set object.

Returns:

Nothing.

References ATE::IParaFeatures::GetRef(), ATE::sTextRanges, and ATE::Throw_ATE_Exception().

void ATE::ITextRanges::Select

(

bool

addToSelection = false

)

Selects the text in this text range set.

Parameters:

addToSelection

(Optional) True to add this text to the current selection, false (the default) to clear the current selection before selecting this text.

Returns:

Nothing.

References ATE::sTextRanges, and ATE::Throw_ATE_Exception().

void ATE::ITextRanges::SetLocalCharFeatures

(

const ICharFeatures &

pFeatures

)

Replaces all of the local overrides for all characters in this text range set with a new set of feature values.

All values that are assigned become local values, replacing any previous local value. These local values override any specified in a style associated with a character or a text range. All values that are unassigned remove any previous local values, so that those values are inherited.

Parameters:

pFeatures

The new feature set object.

Returns:

Nothing.

References ATE::ICharFeatures::GetRef(), ATE::sTextRanges, and ATE::Throw_ATE_Exception().

void ATE::ITextRanges::SetLocalParaFeatures

(

const IParaFeatures &

pFeatures

)

Replaces all of the local overrides for all paragraphs in this text range set with a new set of feature values.

All values that are assigned become local values, replacing any previous local value. These local values override any specified in a style associated with a paragraph or a text range. All values that are unassigned remove any previous local values, so that those values are inherited.

Parameters:

pFeatures

The new feature set object.

Returns:

Nothing.

References ATE::IParaFeatures::GetRef(), ATE::sTextRanges, and ATE::Throw_ATE_Exception().

---

The documentation for this class was generated from the following files:

• IText.h
• IText.cpp