ATE::IFind Class Reference

This class encapsulates a search through text. More...

#include <IText.h>

Public Member Functions
	IFind ()
	Constructor.
	IFind (const IFind &src)
	Copy constructor.
IFind &	operator= (const IFind &rhs)
	Assignment operator.
bool	operator== (const IFind &rhs) const
	Comparison operator tests for equality.
bool	operator!= (const IFind &rhs) const
	Comparison operator tests for inequality.
	IFind (FindRef find)
	Constructs this C++ object from the corresponding C object returned by an ATE suite function.
virtual	~IFind ()
	Destructor.
FindRef	GetRef () const
	Retrieves a reference to this object.
bool	IsNull () const
	Reports whether this is a null object.
Direction	GetSearchDirection () const
	Retrieves the direction of search, front-to-back or back-to-front.
bool	GetIgnoreCase () const
	Reports whether searching is case-sensitive.
bool	GetWholeWord () const
	Reports whether searching matches whole words.
bool	GetWrap () const
	Reports whether searching wraps.
bool	GetFindWordsOutOfBounds () const
	Reports whether searching should continue beyond selected text.
bool	GetIgnoreAccents () const
	Reports whether accents are to be ignored during the find.
bool	GetIgnoreKashidas () const
	Reports whether kashidas are to be ignored during the find.
void	SetSearchDirection (Direction newValue)
	Sets the direction of search, front-to-back or back-to-front.
void	SetIgnoreCase (bool newValue)
	Sets whether searching is case-sensitive.
void	SetWholeWord (bool newValue)
	Sets whether searching matches whole words.
void	SetWrap (bool newValue)
	Sets whether searching wraps, ignoring line breaks.
void	SetFindWordsOutOfBounds (bool newValue)
	Sets whether searching matches words that are out-of-bounds.
void	SetIgnoreAccents (bool newValue)
	Sets whether accents should be ignored during the find.
void	SetIgnoreKashidas (bool newValue)
	Sets whether kashidas are to be ignored during the find.
SearchScope	GetSearchScope () const
	Retrieves the scope of the search, the entire document or the current `IStory`.
void	SetSearchScope (SearchScope searchScope)
	Sets the scope of the search to be the entire document or the current `IStory`.
void	SetSearchRange (ITextRange pRange)
	Sets the range of this search to a specific text range.
void	SetSearchChars (ATETextDOM::Unicode *pSearchChars)
	Sets the character string that this search tries to match within the range and scope.
void	GetSearchChars (ATETextDOM::Unicode *pSearchChars, ATETextDOM::Int32 length) const
	Retrieves the character string that this search tries to match.
void	SetReplaceChars (ATETextDOM::Unicode *pSearchChars)
	Sets the character string that this search uses to replace matches found within the range and scope.
void	GetReplaceChars (ATETextDOM::Unicode *pSearchChars, ATETextDOM::Int32 length) const
	Retrieves the character string that this search uses to replace matches found within the range and scope.
void	Reset ()
bool	FindMatch (ITextRange pTextRange)
	Searches for the match string in the specified text range.
bool	FindNextMatch (ITextRange pTextRange)
	Searches for the match string starting at the end of the current selection in the specified text range.
bool	ReplaceMatch (ITextRange pTextRange, bool findNext)
	Searches for the match string in specified text range and replaces it, if found, with the replacement string.
bool	FindAndReplaceAllMatches (ATETextDOM::Int32 *pReplaceCount)
void	GetPreReplaceAllSettings (ATETextDOM::Int32 pCurrentPoint, ATETextDOM::Int32 pStartPoint) const
	Retrieves the current position markers in this object, so that they can be saved before a global search or replacement operation.
void	RestorePreReplaceAllSettings (const ATETextDOM::Int32 currentPoint, const ATETextDOM::Int32 startPoint)
	Restores the current position markers in this object after a global search or replacement operation.

Detailed Description

This class encapsulates a search through text.

The methods allow you to find and replace text in a document using various kinds of character matching.

To find or replace all matches in the search scope, do the following:

Save the text object you are currently working with.
Retrieve the current search position markers with GetPreReplaceAllSettings() and save them.
Implement a loop through all text objects, using FindMatch(), FindNextMatch(), and ReplaceMatch() to find or replace all occurances of your match string.
Keep track of how many matches or replacements were found, to report back to the user.
Restore the previous search position markers with RestorePreReplaceAllSettings()
Restore the working text object with SetSearchRange().

Constructor & Destructor Documentation

ATE::IFind::IFind ( )

Constructor.

Returns:: The new object.

ATE::IFind::IFind ( const IFind & src )

Copy constructor.

Parameters:

src

The object to copy.

Returns:: The new object.

References ATE::sFind.

ATE::IFind::IFind ( FindRef find ) [explicit]

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

The C++ object manages reference counting.

Parameters:

find

The C object.

Returns:: The new C++ object.

ATE::IFind::~IFind ( ) [virtual]

Destructor.

References ATE::sFind.

Member Function Documentation

bool ATE::IFind::FindAndReplaceAllMatches ( ATETextDOM::Int32 * pReplaceCount )

Deprecated:: Do not use. See class description of IFind.

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

bool ATE::IFind::FindMatch ( ITextRange pTextRange )

Searches for the match string in the specified text range.

Parameters:

pTextRange

The text range within which to search.

Returns:: True if a match is found, false otherwise.

See also:: SetSearchChars()

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

bool ATE::IFind::FindNextMatch ( ITextRange pTextRange )

Searches for the match string starting at the end of the current selection in the specified text range.

Parameters:

pTextRange

The text range object.

Returns:: True if a match is found, false otherwise.

See also:: SetSearchChars()

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

bool ATE::IFind::GetFindWordsOutOfBounds ( ) const

Reports whether searching should continue beyond selected text.

Returns:: True if the search is set to go out-of-bounds.

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

bool ATE::IFind::GetIgnoreAccents ( ) const

Reports whether accents are to be ignored during the find.

Returns:: True if accents are to be ignored, false if they are not.

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

bool ATE::IFind::GetIgnoreCase ( ) const

Reports whether searching is case-sensitive.

Returns:: True if the search is set to ignore case, false if it is case-sensitive.

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

bool ATE::IFind::GetIgnoreKashidas ( ) const

Reports whether kashidas are to be ignored during the find.

Returns:: True if kashidas are to be ignored, false if they are not.

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

void ATE::IFind::GetPreReplaceAllSettings	(	ATETextDOM::Int32 *	pCurrentPoint,
		ATETextDOM::Int32 *	pStartPoint
	)			const

Retrieves the current position markers in this object, so that they can be saved before a global search or replacement operation.

Parameters:

	pCurrentPoint	A buffer in which to return the 0-based index to the current position.
	pStartPoint	A buffer in which to return the 0-based index to the starting position.

Returns:: Nothing.

See also:: Class description of IFind.

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

FindRef ATE::IFind::GetRef ( ) const

Retrieves a reference to this object.

Returns:: The object reference.

void ATE::IFind::GetReplaceChars	(	ATETextDOM::Unicode *	pSearchChars,
		ATETextDOM::Int32	length
	)			const

Retrieves the character string that this search uses to replace matches found within the range and scope.

Parameters:

	pSearchChars	[out] A buffer in which to return the replacement string.
	length	The number of characters in the buffer. Only this much of the replacement string is returned.

Returns:: Nothing.

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

void ATE::IFind::GetSearchChars	(	ATETextDOM::Unicode *	pSearchChars,
		ATETextDOM::Int32	length
	)			const

Retrieves the character string that this search tries to match.

Parameters:

	pSearchChars	[out] A buffer in which to return the search string.
	length	The number of characters in the buffer. Only this much of the search string is returned.

Returns:: Nothing.

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

Direction ATE::IFind::GetSearchDirection ( ) const

Retrieves the direction of search, front-to-back or back-to-front.

Returns:: The direction constant.

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

SearchScope ATE::IFind::GetSearchScope ( ) const

Retrieves the scope of the search, the entire document or the current IStory.

The default scope is the entire document.

Returns:: The search-scope constant.

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

bool ATE::IFind::GetWholeWord ( ) const

Reports whether searching matches whole words.

Returns:: True if the search is set to match whole words.

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

bool ATE::IFind::GetWrap ( ) const

Reports whether searching wraps.

Returns:: True if the search is set to wrap.

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

bool ATE::IFind::IsNull ( ) const

Reports whether this is a null object.

Returns:: True if this is a null object.

References ATE::sFind.

bool ATE::IFind::operator!= ( const IFind & 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.

IFind & ATE::IFind::operator= ( const IFind & rhs )

Assignment operator.

Parameters:

rhs

The object to assign to this one.

Returns:: A reference to this object.

References ATE::sFind.

bool ATE::IFind::operator== ( const IFind & 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.

bool ATE::IFind::ReplaceMatch	(	ITextRange	pTextRange,
		bool	findNext
	)

Searches for the match string in specified text range and replaces it, if found, with the replacement string.

Parameters:

	pTextRange	The text range object.
	findNext	When true, searches in the current selection. When false, begins searching at the end of the current selection.

Returns:: If findNext parameter is true this function will return true if there is another occurance found after the one just replaced, and will return false if there is no other occurance found. If findNext is false this function will always return false.

See also:: SetSearchChars(), SetReplaceChars()

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

void ATE::IFind::Reset ( )

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

void ATE::IFind::RestorePreReplaceAllSettings	(	const ATETextDOM::Int32	currentPoint,
		const ATETextDOM::Int32	startPoint
	)

Restores the current position markers in this object after a global search or replacement operation.

Parameters:

	currentPoint	The saved 0-based index to the current position.
	startPoint	The saved 0-based index to the starting position.

Returns:: Nothing.

See also:: Class description of IFind.

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

void ATE::IFind::SetFindWordsOutOfBounds ( bool newValue )

Sets whether searching matches words that are out-of-bounds.

Parameters:

newValue

True to turn out-of-bounds matching on, false to turn it off.

Returns:: Nothing.

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

void ATE::IFind::SetIgnoreAccents ( bool newValue )

Sets whether accents should be ignored during the find.

Parameters:

newValue

True to ignore accents.

Returns:: Nothing.

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

void ATE::IFind::SetIgnoreCase ( bool newValue )

Sets whether searching is case-sensitive.

Parameters:

newValue

True to set the search to ignore case, false to make it case-sensitive.

Returns:: Nothing.

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

void ATE::IFind::SetIgnoreKashidas ( bool newValue )

Sets whether kashidas are to be ignored during the find.

Parameters:

newValue

True to ignore kashidas.

Returns:: Nothing.

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

void ATE::IFind::SetReplaceChars ( ATETextDOM::Unicode * pSearchChars )

Sets the character string that this search uses to replace matches found within the range and scope.

Parameters:

pSearchChars

The replacement string.

Returns:: Nothing.

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

void ATE::IFind::SetSearchChars ( ATETextDOM::Unicode * pSearchChars )

Sets the character string that this search tries to match within the range and scope.

Parameters:

pSearchChars

The search string.

Returns:: Nothing.

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

void ATE::IFind::SetSearchDirection ( Direction newValue )

Sets the direction of search, front-to-back or back-to-front.

Parameters:

newValue

The direction constant.

Returns:: Nothing.

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

void ATE::IFind::SetSearchRange ( ITextRange pRange )

Sets the range of this search to a specific text range.

Use to restore the range after a global search or replace operation.

Parameters:

pRange

The text range object.

Returns:: Nothing.

See also:: Class description of IFind.

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

void ATE::IFind::SetSearchScope ( SearchScope searchScope )

Sets the scope of the search to be the entire document or the current IStory.

The default scope is the entire document.

Parameters:

searchScope

The search-scope constant.

Returns:: Nothing.

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

void ATE::IFind::SetWholeWord ( bool newValue )

Sets whether searching matches whole words.

Parameters:

newValue

True to turn whole-word matching on, false to turn it off.

Returns:: Nothing.

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

void ATE::IFind::SetWrap ( bool newValue )

Sets whether searching wraps, ignoring line breaks.

Parameters:

newValue

True to turn wrapping on, false to turn it off.

Returns:: Nothing.

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

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

ATE::IFind Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation