SplInit

This function is called by an application to initialize a spelling session. SplInit generates a handle for a spelling session, allocates buffer memory, loads the main dictionary and external user dictionaries, and creates the internal user dictionaries.

int SplInit( 
HSPL * phspl, 
int clex, 
WCHAR ** ppwsz );

Parameters

• phspl
  Pointer to the handle of the new spelling session. The SplInit function creates this handle and places it at the location pointed to by this parameter. Subsequent calls by an application must include this handle to associate a call to a particular spelling session.
• clex
  Number of user dictionaries that are defined. If clex is 0, the SplCheck function uses only the main dictionary.
• ppwsz
  Pointer to a list of pointers, each of which point to a null-terminated string that contains the path and file name for an external user dictionary. If clex is 0, this parameter must be NULL.

Return Values

1 indicates success. 0 indicates failure.

Remarks

Windows CE supplies a read-only main spelling dictionary on the device. By default, this dictionary is used during every spelling session. Currently, Windows CE does not support replacing this main dictionary with a dictionary supplied by the application.

In addition to loading the main dictionary, SplInit creates the following three internal user dictionaries:

• SPL_IGNORE_LEX
  Contains words that the spelling checker finds, but the user does not want to change. The spelling checker ignores words in this list for the remainder of the spelling session.
• SPL_CHANGE_ALWAYS_LEX
  Contains words that the spelling checker finds, paired with words that replace subsequent occurrences of the found words.
• SPL_CHANGE_ONCE
  Contains words that the spelling checker finds and the user changes. The spelling checker continues to find subsequent occurrences of the words.

These internal dictionaries are empty at initialization and removed by the SplQuit function when the spelling session is over.

The application can also specify external user dictionaries to load. The ppwsz parameter points to a list of pointers, each of specify the path and file name of an external user dictionary. If you load one external user dictionary, ppwsz is a pointer to a single pointer. Use the clex parameter to indicate how many external user dictionaries to load. There is no limit to the number of external user dictionaries the application can define.

External user dictionaries are typically created by the user and saved for use during future spelling sessions when an application calls the SplQuit function. During a spelling session, applications can add words to an external user dictionary using SplAddUserDict, remove words using SplRemUserDict, and clear the contents of an external user dictionary using SplClrUserDict.

SplInit assigns identifiers to the internal user dictionaries and to any external user dictionaries pointed to by ppwsz. Use these identifiers in other spelling functions to specify a dictionary. The parameter that identifies a dictionary is nID. Values that SplInit assigns to nID are listed in the following table.

To determine the value of the nID parameter for an external user dictionary, subtract one from its position in the dictionary list that the ppwsz parameter points to. For example, if there are three external user dictionaries to load, clex equals 3. The nID of the last dictionary loaded is clex–1, which equals 2.

Because initializing a spelling session is time-consuming, consider doing it when the calling application starts and keeping the spelling session active until the calling application ends. Remember, however, that a spelling session has exclusive access to external user dictionaries until the calling application exits. This means that a second application cannot load external user dictionaries that are already in use.

If it is possible for a user to simultaneously run multiple applications that can use the spelling checker, it might be best to initialize the spelling checker when the user requests it instead of initializing it when the calling application starts. When the application is done with the spelling checker, it calls the SplQuit function and the external user dictionary or dictionaries are available for use by another spelling session.

The main dictionary is available for multiple spelling sessions because it is read-only. The internal user dictionaries are created for each spelling session and removed at the end of each session; therefore, access to them by multiple spelling sessions is not an issue.

Requirements

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

SplAddUserDict, SplClrUserDict, SplQuit, SplRemUserDict

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.