Next Page > Hide TOC

NSSpellChecker Class Reference

Overview

The NSSpellChecker class provides an interface to the Cocoa spell-checking service. To handle all its spell checking, an application needs only one instance of NSSpellChecker, known as the spell checker. Through the spell checker you manage the Spelling panel, in which the user can specify decisions about words that are suspect.

The spell checker also offers the ability to provide word completions to augment the text completion system in Mac OS X v10.3.

Tasks

Getting the Spell Checker

• + sharedSpellChecker
• + sharedSpellCheckerExists

Configuring Spell Checkers

• – availableLanguages
• – language
• – setLanguage:

Managing the Spelling Panel

• – accessoryView
• – setAccessoryView:
• – spellingPanel
• – updateSpellingPanelWithGrammarString:detail:

Using Spell Checkers

• – countWordsInString:language:
• – checkSpellingOfString:startingAt:
• – checkSpellingOfString:startingAt:language:wrap:inSpellDocumentWithTag:wordCount:
• – guessesForWord:
• – checkGrammarOfString:startingAt:language:wrap:inSpellDocumentWithTag:details:

Managing the Spell-Checking Process

• + uniqueSpellDocumentTag
• – closeSpellDocumentWithTag:
• – ignoreWord:inSpellDocumentWithTag:
• – ignoredWordsInSpellDocumentWithTag:
• – setIgnoredWords:inSpellDocumentWithTag:
• – setWordFieldStringValue:
• – updateSpellingPanelWithMisspelledWord:
• – completionsForPartialWordRange:inString:language:inSpellDocumentWithTag:
• – hasLearnedWord:
• – unlearnWord:

Class Methods

sharedSpellChecker

Returns the NSSpellChecker (one per application).

+ (NSSpellChecker *)sharedSpellChecker

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + sharedSpellCheckerExists

Related Sample Code

• SpellingChecker CarbonCocoa Bundled
• SpellingChecker-CarbonCocoa
• SpellingChecker-CocoaCarbon

Declared In

sharedSpellCheckerExists

Returns whether the application’s NSSpellChecker has already been created.

+ (BOOL)sharedSpellCheckerExists

Availability

• Available in Mac OS X v10.0 and later.

See Also

• + sharedSpellChecker

Declared In

uniqueSpellDocumentTag

Returns a guaranteed unique tag to use as the spell-document tag for a document.

+ (NSInteger)uniqueSpellDocumentTag

Discussion

Use this method to generate tags to avoid collisions with other objects that can be spell checked.

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• SpellingChecker CarbonCocoa Bundled
• SpellingChecker-CarbonCocoa
• SpellingChecker-CocoaCarbon

Declared In

Instance Methods

accessoryView

Returns the Spelling panel’s accessory NSView object.

- (NSView *)accessoryView

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAccessoryView:

Declared In

availableLanguages

Provides the languages preferred by the user.

- (NSArray *)availableLanguages

Return Value

List of language names.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

checkGrammarOfString:startingAt:language:wrap:inSpellDocumentWithTag:details:

Initiates a grammatical analysis of a given string.

- (NSRange)checkGrammarOfString:(NSString *)string startingAt:(NSInteger)start language:(NSString *)language wrap:(BOOL)wrap inSpellDocumentWithTag:(NSInteger)documentTag details:(NSArray **)outDetails

Parameters

string

String to analyze.

start

Location within string at which to start the analysis.

language

Language use in string. When nil, the language selected in the Spelling panel is used.

wrap

YES to specify that the analysis continue to the beginning of string when the end is reached.

NO to have the analysis stop at the end of string.

documentTag

Identifies the spell document with ignored words to use.

outDetails

On output, dictionaries describing grammar-analysis details within the flagged grammatical unit. See the NSSpellServer class for information about these dictionaries.

Return Value

Location of the first flagged grammatical unit.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

checkSpellingOfString:startingAt:

Starts the search for a misspelled word in stringToCheck starting at startingOffset within the string object.

- (NSRange)checkSpellingOfString:(NSString *)stringToCheck startingAt:(NSInteger)startingOffset

Discussion

Returns the range of the first misspelled word. Wrapping occurs, but no ignored-words dictionary is used.

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• SpellingChecker CarbonCocoa Bundled
• SpellingChecker-CarbonCocoa
• SpellingChecker-CocoaCarbon

Declared In

checkSpellingOfString:startingAt:language:wrap:inSpellDocumentWithTag:wordCount:

Starts the search for a misspelled word in a string starting at specified offset within the string.

- (NSRange)checkSpellingOfString:(NSString *)stringToCheck startingAt:(NSInteger)startingOffset language:(NSString *)language wrap:(BOOL)wrapFlag inSpellDocumentWithTag:(NSInteger)tag wordCount:(NSInteger *)wordCount

Parameters

stringToCheck

The string object containing the words to spellcheck.

startingOffset

The offset within stringToCheck at which to begin spellchecking.

language

The language of the words in the string. If language is nil, or if you obtain the value by sending language to self, the current selection in the Spelling panel’s pop-up menu is used. Do not pass in an empty string for language.

wrapFlag

YES to indicate that spell checking should continue at the beginning of the string when the end of the string is reached; NO to indicate that spellchecking should stop at the end of the document.

tag

An identifier unique within the application used to inform the spell checker which document (actually, a dictionary) of ignored words to use.

wordCount

Returns by indirection a count of the words spell-checked up to and including the first error (if any), or -1 if the spell checker fails or does not support word counting. Specify NULL if you do not want this word count.

Return Value

The range of the first misspelled word and optionally (and by reference) the count of words spellchecked in the string in wordCount.

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• SpellingChecker CarbonCocoa Bundled
• SpellingChecker-CarbonCocoa
• SpellingChecker-CocoaCarbon

Declared In

closeSpellDocumentWithTag:

Notifies the receiver that the user has finished with the ignored-word document identified by tag, causing it to throw that dictionary away.

- (void)closeSpellDocumentWithTag:(NSInteger)tag

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• SpellingChecker CarbonCocoa Bundled
• SpellingChecker-CarbonCocoa
• SpellingChecker-CocoaCarbon

Declared In

completionsForPartialWordRange:inString:language:inSpellDocumentWithTag:

Provides a list of complete words that the user might be trying to type based on a partial word in a given string.

- (NSArray *)completionsForPartialWordRange:(NSRange)partialWordRange inString:(NSString *)string language:(NSString *)language inSpellDocumentWithTag:(NSInteger)spellDocumentTag

Parameters

partialWordRange

Range that identifies a partial word in string.

string

String with the partial word from which to generate the result.

language

Language to used in string. When nil, this method uses the language selected in the Spelling panel.

spellDocumentTag

Identifies the spell document with ignored words to use.

Return Value

List of complete words from the spell checker dictionary in the order they should be presented to the user.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

countWordsInString:language:

Returns the number of words in stringToCount.

- (NSInteger)countWordsInString:(NSString *)stringToCount language:(NSString *)language

Discussion

The language argument specifies the language used in the string. If language is nil, the current selection in the Spelling panel’s pop-up menu is used.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

guessesForWord:

Returns an array of suggested spellings for the misspelled word word.

- (NSArray *)guessesForWord:(NSString *)word

Discussion

If word contains all capital letters, or its first letter is capitalized, the suggested words are capitalized in the same way.

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• SpellingChecker CarbonCocoa Bundled
• SpellingChecker-CarbonCocoa
• SpellingChecker-CocoaCarbon

Declared In

hasLearnedWord:

Indicates whether the spell checker has learned a given word.

- (BOOL)hasLearnedWord:(NSString *)word

Parameters

word

Word in question.

Return Value

YES when the spell checker has learned word, NO otherwise.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

ignoredWordsInSpellDocumentWithTag:

Returns the array of ignored words for a document identified by tag.

- (NSArray *)ignoredWordsInSpellDocumentWithTag:(NSInteger)tag

Discussion

Invoke this method before closeSpellDocumentWithTag: if you want to store the ignored words.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setIgnoredWords:inSpellDocumentWithTag:

Related Sample Code

• SpellingChecker CarbonCocoa Bundled
• SpellingChecker-CarbonCocoa
• SpellingChecker-CocoaCarbon

Declared In

ignoreWord:inSpellDocumentWithTag:

Instructs the spell checker to ignore all future occurrences of wordToIgnore in the document identified by tag.

- (void)ignoreWord:(NSString *)wordToIgnore inSpellDocumentWithTag:(NSInteger)tag

Discussion

You should invoke this method from within your implementation of the NSIgnoreMisspelledWords protocol’s ignoreSpelling: method.

Availability

• Available in Mac OS X v10.0 and later.

Related Sample Code

• SpellingChecker CarbonCocoa Bundled
• SpellingChecker-CarbonCocoa
• SpellingChecker-CocoaCarbon

Declared In

language

Returns the current language used in spell checking.

- (NSString *)language

Discussion

The result string specifies the language using the language and regional designations described in Language and Locale Designations in Internationalization Programming Topics.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setLanguage:

Declared In

setAccessoryView:

Makes an NSView object an accessory of the Spelling panel by making it a subview of the panel’s content view.

- (void)setAccessoryView:(NSView *)aView

Discussion

This method posts an NSWindowDidResizeNotification with the Spelling panel object to the default notification center.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – accessoryView

Declared In

setIgnoredWords:inSpellDocumentWithTag:

Initializes the ignored-words document (a dictionary identified by tag with someWords), an array of words to ignore.

- (void)setIgnoredWords:(NSArray *)someWords inSpellDocumentWithTag:(NSInteger)tag

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – ignoredWordsInSpellDocumentWithTag:

Related Sample Code

• SpellingChecker CarbonCocoa Bundled
• SpellingChecker-CarbonCocoa
• SpellingChecker-CocoaCarbon

Declared In

setLanguage:

Sets the language to use in spell checking to language.

- (BOOL)setLanguage:(NSString *)language

Discussion

Returns whether the Language pop-up list in the Spelling panel lists language.

Listing 1 shows how languages can be specified in language. If the language specified is listed in the user’s list of preferred languages, the spell checker uses that language to accomplish its task.

Listing 1  Specifying the spell checker language

NSSpellChecker* spell_checker = [NSSpellChecker sharedSpellChecker];

[spell_checker setLanguage:@"fr"];     // Sets language to French. The language method returns "fr".

[spell_checker setLanguage:@"NL"];     // Sets language to the one spoken in Netherlands (English). The language method returns "en".

[spell_checker setLanguage:@"en_GB"]   // Sets language to British English. The language method returns "en_GB".

[spell_checker setLanguage:@"German"]; // Sets language to German. The language method returns "de".

To learn about the strings you can use to specify a language in language, see Language and Locale Designations in Internationalization Programming Topics.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – language

Declared In

setWordFieldStringValue:

Sets the string that appears in the misspelled word field, using the string object aString.

- (void)setWordFieldStringValue:(NSString *)aString

Availability

• Available in Mac OS X v10.0 and later.

Declared In

spellingPanel

Returns the spell checker’s panel.

- (NSPanel *)spellingPanel

Availability

• Available in Mac OS X v10.0 and later.

Declared In

unlearnWord:

Tells the spell checker to unlearn a given word.

- (void)unlearnWord:(NSString *)word

Parameters

word

Word to unlearn.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

updateSpellingPanelWithGrammarString:detail:

Specifies a grammar-analysis detail to highlight in the Spelling panel.

- (void)updateSpellingPanelWithGrammarString:(NSString *)problemString detail:(NSDictionary *)detail

Parameters

problemString

Problematic grammatical unit identified by chechGrammarOfString:startingAt:language:wrap:inSpellingDocumentWithTag:details:.

detail

One of the grammar-analysis details provided by chechGrammarOfString:startingAt:language:wrap:inSpellingDocumentWithTag:details:.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

updateSpellingPanelWithMisspelledWord:

Causes the spell checker to update the Spelling panel’s misspelled-word field to reflect word.

- (void)updateSpellingPanelWithMisspelledWord:(NSString *)word

Discussion

You are responsible for highlighting word in the document and for extracting it from the document using the range returned by the checkSpelling:... methods. Pass the empty string as word to have the system beep, indicating no misspelled words were found.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Next Page > Hide TOC