Wintertree Software Inc.

WSpell ActiveX Spelling Checker Control

Home Site index Contact us Catalog Shopping Cart Products Support Search

You are here: Home > Products > Developer tools > WSpell > Technical details


Technical details

Summary:

Properties, methods, and events

WSpell's rich set of properties, methods and events give it the flexibility to support virtually all spell-check requirements.

Properties

All of WSpell's properties have reasonable defaults so you need to change or set only a small number of properties to suit your application's requirements.

AutoCorrect

WSpell can automatically replace one word with another (e.g., replace a frequently misspelled word with its correction, or replace an abbreviation with its expansion). This property turns automatic correction on or off.

CaseSensitive

Controls whether WSpell checks spelling with regard to differences in letter case (e.g., treating america and America as two separate words) or by ignoring differences in letter case. (e.g., treating america and America as the same word). Keeping this property enabled improves performance (because Wintertree Software's dictionaries are optimized for case-sensitive access) and ensures that capitalization errors are detected. You might disable this property when checking text entered in all-caps, for example.

CanUndo

This property is set to True when the user has made a change to the checked text which can be undone. This property is useful for enabling an "Undo" button in a dialog box, for example.

CatchDoubledWords

WSpell can automatically detect the same word appearing twice in a row (e.g., Minutes of the the meeting were filed yesterday.) This property controls whether doubled words are reported to the user or your application (via the DoubledWord event).

CatchMixedCaseWords

WSpell can automatically detect words which have an unusual combination of upper- and lower-case letters (e.g., TUesday). This property controls whether mixed-case words are reported to the user or your application (via the MixedCaseWord event).

CatchWordsWithDigits

WSpell can automatically detect words which contain embedded digits, which might result from accidentally omitting a space (e.g., Monday14 August). This property controls whether words with embedded digits are reported to the user or your application (via the WordWithDigits event).

CurrentWord

Contains the current word in the text being checked. Your application can use this property to iterate through all words in the text, or to replace the current word with another word.

DialogLeft

This property sets the x coordinate of the built-in spell check dialog box.

DialogTop

This property sets the y coordinate of the built-in spell check dialog box.

IgnoreAllCapsWords

Controls whether WSpell automatically skips (ignores) words containing just capital letters. If the text contains many abbreviations or acronyms, setting this property prevents them from being reported as spelling errors.

IgnoreCapitalizedWords

Controls whether WSpell automatically skips (ignores) words starting with a capital letter. If the text contains many proper names, setting this property prevents them from being reported as spelling errors.

IgnoreDomainNames

Controls whether WSpell automatically skips (ignores) words which appear to be Internet domain names.

IgnoreHTMLMarkups

Controls whether WSpell skips (ignores) HTML markups in text. When this property is set to True, WSpell can be used to spell-check the visible portion of HTML.

IgnoreMixedCaseWords

Controls whether WSpell automatically skips (ignores) words which contain a mixture of upper- and lower-case letters. If the text contains variable names, technical jargon, etc. (e.g., YearToDate, FmtString), setting this property prevents them from being reported as spelling errors.

IgnoreNonAlphaWords

Controls whether WSpell automatically skips (ignores) words which contain no alphabetic letters. When checking general text, enabling this property will prevent non-alphabetic strings like phone numbers and ZIP codes from being reported as spelling errors. WSpell is flexible enough that it can be used for purposes such as validating part numbers, in which case this property would be disabled.

IgnoreWordsWithDigits

Controls whether WSpell automatically skips (ignores) words which contain embedded digits. When checking general text, enabling this property will prevent strings like product codes from being reported as spelling errors. WSpell is flexible enough that it can be used for purposes such as validating product codes and part numbers, in which case this property would be disabled.

MainDictionary

Used to access the set of main dictionary files. Wintertree Software's main dictionaries are usually implemented as two files, and you may supplement them with application-specific terms. This indexed property is used to access the name of each individual main dictionary file.

MainDictionaryCount

Contains the number of main dictionary files currently open. This property is useful for limiting the index used in the MainDictionary property.

MainDictionaryFiles

Contains the set of main dictionary files, listed as a comma-delimited string. Setting this property closes the current set of main dictionary files and opens a new set.

MaxSuggestions

Specifies the maximum number of suggestions offered by the Suggest method. The Suggest method locates the best MaxSuggestions suggestions.

MinSuggestionDepth

Contains the initial search depth used by the Suggest method. See Locating Suggestions for a discussion of search depths. Setting this property to a low value makes the Suggest method run faster, but also decreases the probability that the correct replacement word will be found. Setting this property to a high value increases both the search time and the probability of success.

MinSuggestionScore

The Suggest method eliminates any suggested word whose score falls below this property's value. This property is useful for limiting the set of suggestions to those which are very similar to the misspelled word.

MisspelledWord

Contains the last misspelled word detected by WSpell.

MisspelledWordCount

Contains the number of misspelled words detected so far in the text being checked.

PhoneticSuggestions

When this property is enabled, the Suggest method locates suggested replacements for misspelled words using phonetic (sounds like) matching. Phonetic matching is best used with words which are badly misspelled, as can happen when checking text entered by children or people learning a second language. (Currently, phonetic matching works only with English pronunciation rules.)

ReplacementWord

Contains the word which will be substituted for the misspelled word when the ReplaceWord method is called.

ShowContext

When this property is enabled, the built-in spelling-checker dialog box will display the contents of the Text property so the user can see misspelled words in their context. If False, the context area will not be shown. This property is useful when checking words contained in text strings.

ShowDialog

When this property is enabled, the built-in spelling-checker dialog box will be presented to the user when the Start method is invoked. The dialog box will appear only if a misspelled word is encountered. If the ShowContext property is True, the dialog will contain a context area which displays the contents of the Text property. If the ShowDialog property is False, the built-in spelling checker dialog box will not be displayed, which allows your application to define its own user interface or to check spelling without a user interface.

SplitContractedWords

When this property is enabled, apostrophes will if necessary be treated as word separators, and each sub-word checked individually. This property is intended for use with Wintertree Software's French and Italian dictionaries.

SplitHyphenatedWords

When this property is enabled, hyphens ("-") will if necessary be treated as word separators, and each sub-word checked individually.

SplitWords

When this property is enabled, words will if necessary be treated as a series of concatenated sub-words, and each sub-word checked individually. This property is intended for use with Wintertree Software's German and Finnish dictionaries.

StripPossessives

When this property is enabled, possessives of the form 's and s' will be removed from words before checking their spelling.

Suggestion

This property is used to index the set of suggestions produced by the Suggest method.

SuggestionCount

Contains the number of suggestions produced by the Suggest method. This property is useful for limiting the index passed to the Suggestion property.

SuggestionDepth

Contains the depth used to locate suggested replacements for misspelled words. See Locating Suggestions for a discussion of suggestion depth. The SuggestionDepth property is automatically set to the value of the MinSuggestionDepth property the first time the Suggest method is called to look up suggestions for a specific word.

SuggestionDepthIncrement

Each time the Suggest method is called, the SuggestionDepth property is increased by the value of this property. See Locating Suggestions for a discussion of suggestion depth.

SuggestionScoreRange

Contains the range of top scores used to filter suggestions. Only suggestions whose score falls within SuggestionScoreRange of the top-scoring suggestion will be offered. This property is useful for limiting the set of suggested words to the best set.

SuggestSplitWords

When this property is enabled, the Suggest method will attempt to split the misspelled word into two, and will offer the split words as suggestions if both are valid words. This is useful for correcting words incorrectly joined by a missing space -- e.g., if this property is enabled, the Suggest method would suggest the dog as a replacement for thedog.

Text

Contains the text to be spell checked. The Text property can contain any number of words (even just one), limited only by memory. The Text property is automatically set to the contents of a text box when the TextControlHWnd property is set.

TextControlHWnd

Contains the hWnd property (i.e., the window handle) of a text box or other text-containing control to be checked. When this property is set, the Text property is set to the text contained by the specified control. If the control is a standard text box or rich-text box, misspelled words will be highlighted and replacements updated automatically. Your application can spell check the contents of a text box by just setting this property and calling the Start method.

TextLength

Contains the current number of characters in the Text property.

TypographicalSuggestions

When this property is enabled, the Suggest method locates suggested replacements for misspelled words using typographical (looks like) matching. Typographical matching is best used with words which contain one or two spelling errors. See the PhoneticSuggestions property for more information.

UndoNewText

Contains the new text inserted in the last undone change. This property is useful for implementing an Undo feature in your own user interface; the built-in spell check dialog box contains an Undo button that automatically performs the processing needed to undo a change.

UndoOffset

Contains the offset of the last undone change in characters from the start of the Text property. This property is useful for implementing an Undo feature in your own user interface; the built-in spell check dialog box contains an Undo button that automatically performs the processing needed to undo a change.

UndoOldText

Contains the original text which was changed in the last undone operation. This property is useful for implementing an Undo feature in your own user interface; the built-in spell check dialog box contains an Undo button that automatically performs the processing needed to undo a change.

UserDictionary

Used to access the set of user dictionary files. This indexed property is used to access the name of each individual user dictionary file.

UserDictionaryCount

Contains the number of user dictionary files currently open. This property is useful for limiting the index used in the UserDictionary property.

UserDictionaryFiles

Contains the set of user dictionary files, listed as a comma-delimited string. Setting this property closes the current set of user dictionary files and opens a new set

UserDictionaryOtherWord

Contains the alternate word associated with a word in a user dictionary. See About user dictionaries and actions for more information on WSpell's user dictionaries.

UserDictionaryWord

Obtains a word at a given index from a user dictionary. The words in a user dictionary can be enumerated by indexing this property.

UserDictionaryWordAction

Contains the action associated with a word in a user dictionary. See About user dictionaries and actions for more information on WSpell's user dictionaries and the action codes which can be associated with words.

UserDictionaryWordCount

Contains a count of the words in a user dictionary. This property is useful for limiting the index passed to the UserDictionaryWord property.

Version

Contains WSpell's version id.

WordCount

Contains the number of words currently in the Text property.

WordOffset

Contains the offset of the start of the current word from the start of the Text property.

WordsReplacedCount

Contains the number of words changed so far in the Text property.

Methods

Methods are the functions your application calls to cause WSpell to perform some action.

AddMainDictionary

Add a new main dictionary file to the set of main dictionaries.

AddUserDictionary

Add a new user dictionary file to the set of user dictionaries.

AddToUserDictionary

Add a word to a specified user dictionary. This method will also optionally associate an action and alternate word with the word. See About user dictionaries and actions for more information on user dictionaries and action codes.

CheckBackgroundNotify

Monitor typing in a rich-text control, and mark misspelled words by changing their appearance (e.g., underline, change to red, etc.). A context menu containing suggested replacements and other spelling-checker actions can be displayed.

ClearTempDictionary

Remove all words from the temporary dictionary used to record words marked ignore-all and replace-all by the user.

CreateUserDictionary

Create a new user dictionary, and add it to the set of user dictionaries. Call this method to create a new user dictionary if the file does not already exist. If the file already exists, use the AddUserDictionary method instead.

DeleteFromUserDictionary

Remove a word from a specified user dictionary.

DeleteWord

Deletes the current word from the Text property. Any leading white space characters are also deleted. This method is useful for removing the second occurrence of a doubled word. This method is called automatically by the built-in spell check dialog box when then Delete button is pressed.

IgnoreAllWord

Causes the current word to be skipped, and all further occurrences of the MisspelledWord to be skipped as well. The word is added to the temporary dictionary. This method is called automatically by the built-in spell check dialog box when the Ignore All button is pressed.

IgnoreWord

Skips over the current word. This method is called automatically by the built-in spell check dialog box when the Ignore button is pressed.

NextWord

Advance to the next word in the text being checked. The CurrentWord property changes to the next word.

RemoveMainDictionary

Remove the specified main dictionary file from the set of main dictionaries.

RemoveUserDictionary

Remove the specified user dictionary file from the set of user dictionaries.

ReplaceAllWord

Substitutes the word in the ReplacementWord property for the current word in the Text property, and substitutes all further occurrences of MisspelledWord with the ReplacementWord. The replacement is added to the temporary dictionary, so the replacements will be made automatically until the temporary dictionary is cleared. This method is called automatically by the built-in spell check dialog box when then Change All button is pressed.

ReplaceWord

Substitutes the word in the ReplacementWord property for the current word in the Text property. This method is called automatically by the built-in spell check dialog box when then Change button is pressed.

Resume

Continue checking the text in the Text property. This method is usually called after detection of a misspelled word has been signaled by the MisspelledWord, Capitalization, MixedCaseWord, or WordWithDigits events. After disposing of the problem (e.g., by calling the IgnoreWord or ReplaceWord methods), your application calls the Resume method to continue checking. Also see the Start method.

ShowOptionsDialog

Calling this method presents the built-in Option dialog box, which is used to set spelling-checker options.

ShowUserDictionaryDialog

Calling this method presents the built-in user-dictionary dialog box, which is used to edit the contents of user dictionaries.

Start

Begin a spelling-check operation. The text in the Text property is checked for spelling errors (including other problems such as doubled words, based on other property settings). If the ShowDialog property is True, the built-in spelling-checker dialog will interact with the user to dispose of any spelling errors found. In this case, the Start method will not return until the spelling check is complete. If the ShowDialog property is False, your application can respond to spelling errors by catching events fired by WSpell.

Suggest

Look up suggested replacements for the word in the MisspelledWord property. See Locating Suggestions for more information on looking up suggestions.

TestWord

Quickly check the spelling of a single word. This method returns True if the word is spelled correctly, and False otherwise.

Undo

Reverses the last change made to the text in the Text property

Events

WSpell fires events to signal various conditions to your application.

Capitalization

Fired when an uncapitalized word is encountered which exists only in capitalized form in the main and user dictionaries.

ConditionallyChangeWord

Fired when a word is encountered which is marked with a conditional-change action in a user dictionary. See About user dictionaries and actions for more information on user dictionaries and action codes.

DeleteWord

Fired when the DeleteWord method is called, after the text has been deleted. The DeleteWord method deletes the current word in the text and any white space characters preceding the current word.

DoubledWord

Fired when a doubled word (the same word appearing twice in a row) is encountered during checking.

EndOfText

Fired after all words in the Text property have been checked.

MisspelledWord

Fired when a misspelled word is encountered.

MixedCaseWord

Fired when a word containing an unusual mixture of upper- and lower-case letters is encountered

ReplaceWord

Fired when the ReplaceWord method is called, after the replacement has been made.

UndoChange

Fired when the Undo method is called, after the change was undone.

WordWithDigits

Fired when a word containing embedded digits is encountered


Looking up suggestions

When WSpell detects a misspelled word, you may want to display a list of suggested replacements. WSpell's built-in spelling-checker dialog does this automatically, but your application can also obtain suggestions by calling WSpell's Suggest method.

To build a set of suggestions, call the Suggest method. The Suggest method locates suggestions for the word in the MisspelledWord property. (Note that you can set the MisspelledWord property to locate suggestions for any word you like.)

After calling the Suggest method, you can access the set of suggested words by indexing the Suggestion property.

Looking up suggestions can be time consuming. WSpell controls the suggestion search with the SuggestionDepth property. SuggestionDepth determines how much of the large main dictionary is searched when locating suggestions. Stated simply, when SuggestionDepth has a low value, only words which are very similar to the word in the MisspelledWord property are considered as candidate suggestions. When SuggestionDepth has a high value, most or all words in the dictionary are considered.

Each time your application calls the Suggest method, SuggestionDepth is increased by the value of the SuggestionDepthIncrement property. Calling Suggest several times in a row results in a deeper and deeper search. When the MisspelledWord property is changed, SuggestionDepth is reset to the value of the MinSuggestionDepth property.

The suggestions are ordered from best to worst, so Suggestion(0) is the best suggestion (or tied for first place).

Internally, WSpell maintains a score for each suggestion. The scores range from 0 (no similarity to the misspelled word) to 100 (a perfect match with the misspelled word). The Suggest method filters suggestions based on their scores according to the MinSuggestionScore and SuggestionScoreRange properties. Your application can adjust the values of these properties to control the quality of the displayed suggestions.

Any suggestions whose score falls below the MinSuggestionScore value are eliminated. If you set MinSuggestionScore to 0, no suggestions will be eliminated, and if you set it to 100, they will all be eliminated.

The SuggestionScoreRange property defines the range of scores, starting with the highest score, which are acceptable. If SuggestionScoreRange is set to 20, and the best suggestion has a score of 87, then only suggestions with scores ranging from 67 (i.e., 87 minus 20) to 87 will be offered. If you set SuggestionScoreRange to 0, no suggestions will be offered. If you set it to 100, all suggestions will be offered.

The Suggest method can locate suggestions using typographical ("looks like") matching, phonetic ("sounds like") matching, or both, based on how the PhoneticSuggestions property and TypographicalSuggestions property are set.


About user dictionaries and actions

You may be familiar with the concept of user dictionaries through working with other applications, such as Microsoft Word or WordPerfect. Typically, applications store in a user dictionary words which are personal to the user, such as the user's family name or business name.

WSpell extends the user dictionary by optionally associating an action code and an alternate word with each word in a user dictionary. The action code tells WSpell what to do when it encounters the word when checking text. For example, one of the action codes tells WSpell to automatically replace the word with the alternate word. If the word in the user dictionary was a word you frequently misspell (such as recieve), WSpell could automatically replace it with the correct spelling (receive). WSpell comes with a user dictionary (correct.tlx) which contains hundreds of words commonly misspelled and their correct replacements.

WSpell supports the following action codes in its user dictionaries:

Auto-change

Automatically replace one word with another. "Automatically" means the word is changed without intervention from the user. Automatic correction can be turned off by disabling the AutoCorrect property, in which case automatic changes behave like conditional changes.

Conditionally change

Conditionally replace one word with another. Usually, the user is prompted to accept the change before the change is made.

Exclude

Treat the word as misspelled, even if it exists in other dictionary files. The word will be reported as misspelled if it is encounter in the checked text, and will not be offered as a suggestion. This action is useful for effectively deleting words from the main dictionary.

Ignore

Treat the word as correctly spelled. This is the typical meaning assigned to words in user dictionaries.


Home Site index Contact us Catalog Shopping Cart Products Support Search


Copyright © 2015 Wintertree Software Inc.