This is the window procedure for the IME Window. IME Window should use this
default procedure instead of WinDefWindowProc. WinDefImeWindowProc dispatches
the IME related messages to the default part windows. IME Window should not
pass IME Related message s if IME does not want default action for those
messages. For the default actions of the part windows, refer to the later
section.
WinDefImeWindowProc's calling syntax is as follows.
MRESULT APIENTRY WinDefImeWindowProc(
HWND hwnd,
ULONG msg,
MPARAM mp1,
MPARAM mp2 );
ΓòÉΓòÉΓòÉ 13.1.5. Part Windows ΓòÉΓòÉΓòÉ
Part Windows
IME can freely display any type of PM window for displaying the Part data
within IMInstance. Those windows are called as Part Windows, e.g., if IME
displays an intermediate conversion string, that window can be called as
Conversion Part Window. The default window procedure for part windows is
WinDefImePartProc instead of WinDefWindowProc.
System also provide the pre-defined Part Window Classes for IME as follows.
- WC_IME_STATUS
- WC_IME_CONVERSION
- WC_IME_CANDIDATE
- WC_IME_INFOMSG
- WC_IME_REGWORD
In case that IME uses the system pre-defined part window, IME should take care
of the following things:
- The owner window of those pre-defined Part windows should be the IME
Window.
- IME Window should pass the messages that are related to those part
windows to WinDefImeWindowProc.
WinDefImePartProc's calling syntax is as follows.
MRESULT APIENTRY WinDefImePartProc(
HWND hwnd,
ULONG msg,
MPARAM mp1,
MPARAM mp2 );
ΓòÉΓòÉΓòÉ 13.2. Initialization of IME ΓòÉΓòÉΓòÉ
When some IME is a default IME for some language, and some application starts
with that language, System will load that IME. After loading of that IME,
ImeInitialize is called for the global initialization. With this call, IME can
be able to notify the system of its capabilities and IME Window related
information, i.e., class name and the function name of the window procedure.
Following picture shows the global IME initialization.
If IME provides the IME Window class name and its window procedure name, system
will register that class for IME as a PUBLIC-like class by registering the
class for each loaded process.
Because the system queries the window procedure address by its function name,
IME should explicitly export that entry with the function name.
As seen in the above picture, ImeInitialize is called after the _DLL_InitTerm
entry if IME have.
IME should not issue any of the PM APIs which require PM message queue within
_DLL_InitTerm entry, otherwise the system cannot boot up in FullScreen mode
only(no-PM environment).
After the global initialization, ImeNotifyEvent with IME_NE_ATTACHIME is called
for each instance initialization. IME should minimize its instance
initialization for the best system performance.
ΓòÉΓòÉΓòÉ 13.3. Termination of IME ΓòÉΓòÉΓòÉ
When IME is no more needed, i.e., no IMInstance refers to that IME, IME is
freed from memory by DosFreeModule call. To let IME have the opportunity to
clean up the global data, ImeTerminate is called just before the last
DosFreeModule.
ΓòÉΓòÉΓòÉ 13.4. Memory management ΓòÉΓòÉΓòÉ
IME should be callable across the processes, the instance data of IME should be
kept in shared memory. It is safe to use the Private Part(which can be
allocated by ImCreateIMIPart function) to hold such instance data in
IMInstance.
ΓòÉΓòÉΓòÉ 13.5. IME Event Handling ΓòÉΓòÉΓòÉ
When IME gets some event through ImeNotifyEvent call, usually IME changes the
IM instance contents and then calls appropriate ImRequestEvent so that the
system will route WM_IMEREQUEST or WM_IMENOTIFY message. Sample pseudo code
will look like this,
ImeNotifyEvent( EventType )
{
switch( EventType )
{
case SomeEvent:
/* IME logic(i.e. no display) processing */
ImRequestIMInstance();
ImRequestIMIPart(); /* if required */
/* Reflect the processing in instance */
ImReleaseIMIPart(); /* if required */
ImReleaseIMInstance();
/* Request event to route */
ImRequestEvent( RequestEvent type for 'SomeEvent' );
break;
:
}
return NO_ERROR;
}
If IME does not call ImRequestEvent for events which needs display change, L3
application(also the default part classes) cannot show IME related display.
ΓòÉΓòÉΓòÉ 13.6. IME Interface ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ 13.6.1. IME Exported Entries ΓòÉΓòÉΓòÉ
IME Exported Entries
Here are the specification of IME exported entries which IME must provide.
These entries are only callable from the system, i.e., not directly callable
from the application. Because IME is callable from non-PM environment, such as
FS or DOS, IME should not issue any of the PM related calls which require the
PM message queue. IME must export all of the API entries listed below. There
are functions which are not mandatory to support. Those functions can be
distinguished by the return code. If the error code ERROR_NOT_SUPPORTED is
available in some function, it means that the function is not mandatory.
ImeConvertString
ImeDeregisterWord
ImeDialog
ImeEnumRegisterWord
ImeEscape
ImeInitialize
ImeNotifyEvent
ImeQueryRegisterWordType
ImeRegisterWord
ImeSetConversionString
ImeTerminate
ΓòÉΓòÉΓòÉ 13.6.1.1. ImeConvertString ΓòÉΓòÉΓòÉ
ImeConvertString
This entry is called to convert the given input string.
Format:
APIRET APIENTRY ImeConvertString(
HIMI hImi,
PSZ pszInput,
PCANDIDATELISTHEADER pCandidateListHeader,
PULONG pulBufferLength,
ULONG ulFlag )
Parameters:
hImi(input) : IMInstance handle.
pszInput(input) : Input string to be converted
pCandidateListHeader(output) : Conversion result.
pulBufferLength(input/output) : On input, length of pCandidateList is required. On output, total buffer size in bytes which is actually copied to pCandidateList is returned. If this parameter is zero on input, total buffer size for whole CandidateL
returned.
ulFlag(input) : Request type which is one of the followings
ICS_CONVERSION - Reading string -> Result string
ICS_REVERSECONVERSION - Result string -> Reading String
Returns:
Success indicator
0 : Successful completion
other : Error occurred
ERROR_NOT_SUPPORTED : This function is not supported.
Remarks: IME Should not call ImRequestEvent call. This API is used just
for getting a conversion result for Level 3 applications.
ΓòÉΓòÉΓòÉ 13.6.1.2. ImeDeregisterWord ΓòÉΓòÉΓòÉ
ImeDeregisterWord
This entry is called to De-register a previously registered word with its
reading from IME.
Format:
APIRET APIENTRY ImeDeregisterWord(
HIMI hImi,
PSZ pszWord,
PSZ pszReading,
ULONG ulWordType )
Parameters: hImi(input) : IMInstance handle. pszWord(input) : Word to
be De-registered. pszReading(input) : Reading for pszWord.
ulWordType(input) : Word type id.
Returns:
Success indicator
0 : Successful completion
other : Error occurred
ERROR_NOT_SUPPORTED : This function is not supported.
Remarks:
ΓòÉΓòÉΓòÉ 13.6.1.3. ImeDialog ΓòÉΓòÉΓòÉ
ImeDialog
This entry is called to open the IME related dialog panels.
Format:
APIRET APIENTRY ImeDialog(
HIMI hImi,
ULONG ulType,
PREGISTERWORDHEADER pRegWord )
Parameters:
hImi(input) : IMInstance handle
ulType(input) : Dialog type to display. This is one of the following values.
IME_DLG_CONFIG : Display a general purpose dialog.
IME_DLG_REGWORD : Displays a register word dialog.
IME_DLG_DICTIONARY : Displays a dictionary related dialog.
pRegWord(input) : Pointer to the REGISTERWORDHEADER structure. This parameger is valid only when the ulType is IME_DLG_REGWORD.
Returns:
Success indicator
0 : Successful completion
other : Error occurred
ERROR_NOT_SUPPORTED : This function is not supported.
Remarks:
It is recommended that IME call ImRequestEvent to route WM_IMEREQUEST
message to IME Window, and then display appropriate dialog panel.
ΓòÉΓòÉΓòÉ 13.6.1.4. ImeEnumRegisterWord ΓòÉΓòÉΓòÉ
ImeEnumRegisterWord
This entry is called to enumerate the registered words.
Format:
APIRET APIENTRY ImeEnumRegisterWord(
HIMI hImi,
PSZ pszWord,
PSZ pszReading,
ULONG ulWordType,
REGISTERWORDENUMPROC pfnCallback,
PVOID pvData )
Parameters:
hImi(input) : IMInstance handle.
pszWord(input) : Word to be enumerated.
pszReading(input) : Reading of the word to be enumerated.
ulWordType(input) : Word type id to be enumerated.
pfnCallback(input) : Callback entry address
pvData(input) : Application data
Returns:
Success indicator
0 : Successful completion
other : Error occurred
ERROR_NOT_SUPPORTED : This function is not supported.
Remarks:
ΓòÉΓòÉΓòÉ 13.6.1.5. ImeEscape ΓòÉΓòÉΓòÉ
ImeEscape
This entry is provide IME aware application with the opportunity to communicate