ATE::ISpell Class Reference

This class allows you to configure and execute spell-checks within a document, story, or text range. More...

#include <IText.h>

Public Member Functions
	ISpell ()
	Constructor.
	ISpell (const ISpell &src)
	Copy constructor.
ISpell &	operator= (const ISpell &rhs)
	Assignment operator.
bool	operator== (const ISpell &rhs) const
	Comparison operator tests for equality.
bool	operator!= (const ISpell &rhs) const
	Comparison operator tests for inequality.
	ISpell (SpellRef spell)
	Constructs this C++ object from the corresponding C object returned by an ATE suite function.
virtual	~ISpell ()
	Destructor.
SpellRef	GetRef () const
	Retrieves a reference to this object.
bool	IsNull () const
	Reports whether this is a null object.
void	Initialize ()
	Initializes this spell-check object with a directory.
bool	IsInitialized ()
	Reports whether this spell-check object has been initialized.
bool	GetIgnoreWordsInAllUppercase () const
	Reports whether this spell-check ignores words that are all uppercase.
bool	GetIgnoreWordsWithNumbers () const
	Reports whether this spell-check ignores words that contain numbers.
bool	GetIgnoreRomanNumerals () const
	Reports whether this spell-check ignores roman numerals.
bool	GetIgnoreRepeatedWords () const
	Reports whether this spell-check ignores repeated words.
bool	GetIgnoreUncapitalizedStartOfSentence () const
	Reports whether this spell-check ignores the uncapitalized first word of a sentence.
bool	GetStrictYeh () const
	Reports whether strict Yeh characters are considered during the spell check.
bool	GetStrictAlef () const
	Reports whether strict Alef characters are considered during the spell check.
void	SetIgnoreWordsInAllUppercase (bool newValue)
	Sets whether this spell-check ignores words that are all uppercase.
void	SetIgnoreWordsWithNumbers (bool newValue)
	Sets whether this spell-check ignores words that contain numbers.
void	SetIgnoreRomanNumerals (bool newValue)
	Sets whether this spell-check ignores roman numerals.
void	SetIgnoreRepeatedWords (bool newValue)
	Sets whether this spell-check ignores repeated word.
void	SetIgnoreUncapitalizedStartOfSentence (bool newValue)
	Sets whether this spell-check ignores uncapitalized first words of sentences.
void	SetStrictYeh (bool newValue)
	Sets whether to consider strict Yeh characters during the spell check.
void	SetStrictAlef (bool newValue)
	Sets whether to consider strict Alef characters during the spell check.
SearchScope	GetSearchScope () const
	Reports the scope of search for this spell-check, the entire document or a story.
void	SetSearchScope (SearchScope searchScope)
	Sets the scope of search for this spell-check, the entire document or a story.
void	SetSearchRange (const ITextRange &pRange, const bool resetEndOfSentence=true, const bool resetCurPos=true)
	Sets the range of search for this spell-check, limiting the search to a specific text range within the scope.
void	Reset ()
	Resets the search temporarily, for a modeless search.
void	ResumeFrom (const ATETextDOM::Int32 resumePoint)
	Resumes this search from a given point.
void	ResumeFromInsertionPoint ()
	Resumes this search from the current insertion point.
bool	FindOneMisspelledWord (SpellCheckingResult pResult, ITextRange pRange, Language pLanguage=NULL)
	Searches from the start of the range for the first occurrance of an unknown word.
ATETextDOM::Int32	GetWordListSize ()
	Retrieves the number of characters in the list of suggested corrections for an unknown word found by `FindOneMisspelledWord()`.
void	GetWordListContents (ATETextDOM::Unicode pWordListBuffer, ATETextDOM::Int32 sizeOfBuffer, ATETextDOM::Int32 pNumberOfWords)
	Retrieves the list of suggested corrections for an unknown word found by `FindOneMisspelledWord()`.
void	Replace (ITextRange pRange, const ATETextDOM::Unicode *pCorrection)
	Replaces a text range with new text.
void	AddSelectedToReplaceAllDict (const ATETextDOM::Unicode *pCorrection)
	Adds the selected text to the replace-all dictionary associating it with a given correction string.
bool	DoReplaceAll ()
void	GetPreReplaceAllSettings (ATETextDOM::Int32 pCurrentPoint, bool pFoundSentenceEnd) const
	Stores search positions before a replace-all operation that you implement using `FindReplaceAllWord()`.
bool	FindReplaceAllWord (ITextRange pRange, const bool firstTimeInThisObject)
	Searches for the current target word in a text range object.
void	RestorePreReplaceAllSettings (const ATETextDOM::Int32 currentPoint, const bool foundSentenceEnd)
	Restores search positions after a replace-all operation that you implement using `FindReplaceAllWord()`.
void	ClearPairDictionary ()
	Manage spell-check dictionaries.
void	AddSelectedToUserDict ()
	Adds the currently selected word to the dictionary associated with this spell-checker.
void	GetUserDictionaryContents ()
	Copies the known-word dictionary for this spell-checker to the internal word list.
bool	AddToUserDictionary (const ATETextDOM::Unicode *pWord)
	Adds a word to the known-word dictionary for this spell-checker.
void	DeleteFromUserDictionary (const ATETextDOM::Unicode *pWord)
	Removes a word from the known-word dictionary for this spell-checker.
bool	WordExistsInUserDictionary (const ATETextDOM::Unicode *pWord)
	Reports whether a word is contained in the known-word dictionary for this spell-checker.
void	AddSelectedToIgnoreList ()
	Adds the currently selected word to the list of words to be ignored by this spell-checker.
void	ClearIgnoreList ()
	Removes all words from the list of words to be ignored by this spell-checker.
Language	GetLanguageOfLastMissingDictionary ()
	Retrieves the language of the most recent missing dictionary.
ATETextDOM::Int32	GetSpellingDictionaryPath (ATETextDOM::Unicode *path)

Detailed Description

This class allows you to configure and execute spell-checks within a document, story, or text range.

Use the object to perform searches for unknown words, replace them with corrected words, and maintain associated dictionaries and word lists.

To implement a replace-all operation,

Save the current text object and search state, using GetSearchRange() and GetPreReplaceAllSettings().
Loop through the text objects, and use FindReplaceAllWord() to find all instances of the target word in the current text object. Keep calling until the method returns false, making sure to set the firstTimeInThisObject flag as needed. When the method returns a text range, select it and call ReplaceSelected().

When the operation is complete, restore the text object using SetSearchRange(), then restore the position and sentence-end flag using RestorePreReplaceAllSettings(). You must do it in this order, because SetSearchRange() resets the flag.

Constructor & Destructor Documentation

ATE::ISpell::ISpell ( )

Constructor.

Returns:: The new object.

ATE::ISpell::ISpell ( const ISpell & src )

Copy constructor.

Parameters:

src

The object to copy.

Returns:: The new object.

References ATE::sSpell.

ATE::ISpell::ISpell ( SpellRef spell ) [explicit]

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

The C++ object manages reference counting.

Parameters:

spell

The C object.

Returns:: The new C++ object.

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

Destructor.

References ATE::sSpell.

Member Function Documentation

void ATE::ISpell::AddSelectedToIgnoreList ( )

Adds the currently selected word to the list of words to be ignored by this spell-checker.

Returns:: Nothing.

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

void ATE::ISpell::AddSelectedToReplaceAllDict ( const ATETextDOM::Unicode * pCorrection )

Adds the selected text to the replace-all dictionary associating it with a given correction string.

Parameters:

pCorrection

The correction string.

Returns:: Nothing.

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

void ATE::ISpell::AddSelectedToUserDict ( )

Adds the currently selected word to the dictionary associated with this spell-checker.

Returns:: Nothing.

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

bool ATE::ISpell::AddToUserDictionary ( const ATETextDOM::Unicode * pWord )

Adds a word to the known-word dictionary for this spell-checker.

Parameters:

pWord

A string containing the word.

Returns:: True if the addition was successful, false if the string contains spaces (multiple words) and no word was added.

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

void ATE::ISpell::ClearIgnoreList ( )

Removes all words from the list of words to be ignored by this spell-checker.

The list is never cleared automatically.

Returns:: Nothing.

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

void ATE::ISpell::ClearPairDictionary ( )

Manage spell-check dictionaries.

Removes all pairs from the pair dictionary associated with this spell-checker. The dictionary is never cleared automatically.

Returns:: Nothing.

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

void ATE::ISpell::DeleteFromUserDictionary ( const ATETextDOM::Unicode * pWord )

Removes a word from the known-word dictionary for this spell-checker.

Parameters:

pWord

A string containing the word.

Returns:: Nothing.

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

bool ATE::ISpell::DoReplaceAll ( )

Deprecated:: Obsolete, do not use. See ISpell class description for information on implementing a replace-all operation.

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

bool ATE::ISpell::FindOneMisspelledWord	(	SpellCheckingResult *	pResult,
		ITextRange	pRange,
		Language *	pLanguage = `NULL`
	)

Searches from the start of the range for the first occurrance of an unknown word.

If a word is found, fills a word list with suggested corrections. To retrieve this list, use GetWordListSize() and GetWordListContents().

Parameters:

	pResult	[out] A buffer in which to return the first unknown word found.
	pRange	[out] A buffer in which to return the text range that contains the returned word.
	pLanguage	[out] Optional. A buffer in which to return the language.

Returns:: True if an unknown word was found and returned, false if the search reached the end of the range without finding an unknown word.

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

bool ATE::ISpell::FindReplaceAllWord	(	ITextRange	pRange,
		const bool	firstTimeInThisObject
	)

Searches for the current target word in a text range object.

Use to implement a replace-all operation, by finding all instances of the target word in all text objects in the range. See ISpell class description.

Parameters:

	pRange	The text range object.
	firstTimeInThisObject	True to indicate that that search is being done in a new text object in your loop.

Returns:: True if the target word is found in the text range.

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

bool ATE::ISpell::GetIgnoreRepeatedWords ( ) const

Reports whether this spell-check ignores repeated words.

Returns:: True if this spell-check ignores repeated words.

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

bool ATE::ISpell::GetIgnoreRomanNumerals ( ) const

Reports whether this spell-check ignores roman numerals.

Returns:: True if this spell-check ignores roman numerals.

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

bool ATE::ISpell::GetIgnoreUncapitalizedStartOfSentence ( ) const

Reports whether this spell-check ignores the uncapitalized first word of a sentence.

Returns:: True if this spell-check ignores the uncapitalized first word of a sentence.

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

bool ATE::ISpell::GetIgnoreWordsInAllUppercase ( ) const

Reports whether this spell-check ignores words that are all uppercase.

Returns:: True if this spell-check ignores words that are all uppercase.

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

bool ATE::ISpell::GetIgnoreWordsWithNumbers ( ) const

Reports whether this spell-check ignores words that contain numbers.

Returns:: True if this spell-check ignores words that contain numbers.

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

Language ATE::ISpell::GetLanguageOfLastMissingDictionary ( )

Retrieves the language of the most recent missing dictionary.

Returns:: The language constant.

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

void ATE::ISpell::GetPreReplaceAllSettings	(	ATETextDOM::Int32 *	pCurrentPoint,
		bool *	pFoundSentenceEnd
	)			const

Stores search positions before a replace-all operation that you implement using FindReplaceAllWord().

Use RestorePreReplaceAllSettings() to restore the positions after the operation. You must also save the text object you are currently working with, and use SetSearchRange() to restore it. See ISpell class description for information on implementing a replace-all operation.

Parameters:

	pCurrentPoint	[out] A buffer in which to save the current search offset.
	pFoundSentenceEnd	[out] A buffer in which to save the current sentence-end flag.

Returns:: Nothing.

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

SpellRef ATE::ISpell::GetRef ( ) const

Retrieves a reference to this object.

Returns:: The object reference.

SearchScope ATE::ISpell::GetSearchScope ( ) const

Reports the scope of search for this spell-check, the entire document or a story.

The default scope is the entire document.

Returns:: The search-scope constant.

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

ATETextDOM::Int32 ATE::ISpell::GetSpellingDictionaryPath ( ATETextDOM::Unicode * path )

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

bool ATE::ISpell::GetStrictAlef ( ) const

Reports whether strict Alef characters are considered during the spell check.

Returns:: True if strict Alef characters are considered, false if they are not.

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

bool ATE::ISpell::GetStrictYeh ( ) const

Reports whether strict Yeh characters are considered during the spell check.

Returns:: True if strict Yeh characters are considered, false if they are not.

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

void ATE::ISpell::GetUserDictionaryContents ( )

Copies the known-word dictionary for this spell-checker to the internal word list.

Use GetWordListSize() and GetWordListContents() to examine the result.

Returns:: Nothing.

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

void ATE::ISpell::GetWordListContents	(	ATETextDOM::Unicode *	pWordListBuffer,
		ATETextDOM::Int32	sizeOfBuffer,
		ATETextDOM::Int32 *	pNumberOfWords
	)

Retrieves the list of suggested corrections for an unknown word found by FindOneMisspelledWord().

Parameters:

	pWordListBuffer	[out] A buffer in which to return the word list. Use `GetWordListSize()` to allocate sufficient space for the string.
	sizeOfBuffer	The number of characters in the passed buffer.
	pNumberOfWords	[out] A buffer in which to return the number of NULL-terminated words in the returned word list.

Returns:: Nothing.

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

ATETextDOM::Int32 ATE::ISpell::GetWordListSize ( )

Retrieves the number of characters in the list of suggested corrections for an unknown word found by FindOneMisspelledWord().

Use to create a string buffer for GetWordListContents().

Returns:: The number of characters in the list.

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

void ATE::ISpell::Initialize ( )

Initializes this spell-check object with a directory.

Returns:: Nothing

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

bool ATE::ISpell::IsInitialized ( )

Reports whether this spell-check object has been initialized.

Returns:: True if this object has been initialized.

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

bool ATE::ISpell::IsNull ( ) const

Reports whether this is a null object.

Returns:: True if this is a null object.

References ATE::sSpell.

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

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

Assignment operator.

Parameters:

rhs

The object to assign to this one.

Returns:: A reference to this object.

References ATE::sSpell.

bool ATE::ISpell::operator== ( const ISpell & 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::ISpell::Replace	(	ITextRange	pRange,
		const ATETextDOM::Unicode *	pCorrection
	)

Replaces a text range with new text.

Parameters:

	pRange	The destination text range object.
	pCorrection	A string containing the replacement text.

Returns:: Nothing.

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

void ATE::ISpell::Reset ( )

Resets the search temporarily, for a modeless search.

Returns:: Nothing.

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

void ATE::ISpell::RestorePreReplaceAllSettings	(	const ATETextDOM::Int32	currentPoint,
		const bool	foundSentenceEnd
	)

Restores search positions after a replace-all operation that you implement using FindReplaceAllWord().

Use GetPreReplaceAllSettings() to store the positions before the operation. You must also save the text object you are currently working with, and use SetSearchRange() to restore it. See ISpell class description for information on implementing a replace-all operation.

Parameters:

	currentPoint	The buffer containing the saved search offset.
	foundSentenceEnd	The buffer containing the saved sentence-end flag.

Returns:: Nothing.

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

void ATE::ISpell::ResumeFrom ( const ATETextDOM::Int32 resumePoint )

Resumes this search from a given point.

Use this if the user has changed the text significantly enough that you need to reset, but you are fairly certain that the text has not been changed before the given point.

Parameters:

resumePoint

A number of characters, the 0-based offset into the text at which to resume.

Returns:: Nothing.

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

void ATE::ISpell::ResumeFromInsertionPoint ( )

Resumes this search from the current insertion point.

Returns:: Nothing.

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

void ATE::ISpell::SetIgnoreRepeatedWords ( bool newValue )

Sets whether this spell-check ignores repeated word.

Parameters:

newValue

True to ignore repeated words, false to report as a spelling error.

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

void ATE::ISpell::SetIgnoreRomanNumerals ( bool newValue )

Sets whether this spell-check ignores roman numerals.

Parameters:

newValue

True to ignore roman numerals, false to report as a spelling error.

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

void ATE::ISpell::SetIgnoreUncapitalizedStartOfSentence ( bool newValue )

Sets whether this spell-check ignores uncapitalized first words of sentences.

Parameters:

newValue

True to ignore uncapitalized first words of sentences, false to report as a spelling error.

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

void ATE::ISpell::SetIgnoreWordsInAllUppercase ( bool newValue )

Sets whether this spell-check ignores words that are all uppercase.

Parameters:

newValue

True to ignore words that are all uppercase, false to report as a spelling error.

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

void ATE::ISpell::SetIgnoreWordsWithNumbers ( bool newValue )

Sets whether this spell-check ignores words that contain numbers.

Parameters:

newValue

True to ignore words that contain numbers, false to report as a spelling error.

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

void ATE::ISpell::SetSearchRange	(	const ITextRange &	pRange,
		const bool	resetEndOfSentence = `true`,
		const bool	resetCurPos = `true`
	)

Sets the range of search for this spell-check, limiting the search to a specific text range within the scope.

Parameters:

	pRange	The text range object.
	resetEndOfSentence	Optional, whether to reset the end-of-sentence marker. Default is true.
	resetCurPos	Optional, whether to reset the cursor position after the search. Default is true.

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

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

Sets the scope of search for this spell-check, the entire document or a story.

The default scope is the entire document.

Parameters:

searchScope

The search-scope constant.

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

void ATE::ISpell::SetStrictAlef ( bool newValue )

Sets whether to consider strict Alef characters during the spell check.

Parameters:

newValue

True to consider strict Alef characters, false to not.

Returns:: Nothing.

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

void ATE::ISpell::SetStrictYeh ( bool newValue )

Sets whether to consider strict Yeh characters during the spell check.

Parameters:

newValue

True to consider strict Yeh characters, false to not.

Returns:: Nothing.

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

bool ATE::ISpell::WordExistsInUserDictionary ( const ATETextDOM::Unicode * pWord )

Reports whether a word is contained in the known-word dictionary for this spell-checker.

Parameters:

pWord

A string containing the word.

Returns:: True if the word is in the dictionary.

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

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

ATE::ISpell Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation