Programming a Software-Based Input Panel

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

When the user accesses the software-based input panel, Windows Embedded CE creates a dedicated software-based input panel thread. The thread creates a software-based input panel window and initializes the software-based input panel. Then, the thread enters a message loop. Within the message loop, the thread responds to messages and user interface (UI) requests from the software-based input panel window. The thread also calls into the IM object, enabling the IM to create child windows in the software-based input panel window. The content of the software-based input panel window is determined by the current IM.

The software-based input panel thread has a special status with the OS. Any window that the software-based input panel thread creates will not be obscured by other windows. Because some UI elements save and clear themselves when they lose focus, the software-based input panel and its child windows do not receive the focus, even if the user currently is using the software-based input panel.

The software-based input panel queries the IM for data through the IInputMethodand IInputMethod2interfaces. The software-based input panel can remove the current IM and replace it with a new IM. The following table shows the methods of the IInputMethodand IInputMethod2interfaces.

Method	Description
IInputMethod::Deselect	Destroys its window and performs IM-specific cleanup procedures.
IInputMethod::GetImData	Sends data from the current input method (IM) to the current application.
IInputMethod::GetInfo	Requests data regarding the new IM, including property flags and the preferred IM size.
IInputMethod::Hiding	Performs any saving routines before the software-based input panel is hidden.
IInputMethod::ReceiveSipInfo	Sends the IM data about the size, placement, and docked status that the IM should use.
IInputMethod::RegisterCallback	Provides the IM with a pointer to the IIMCallbackinterface.
IInputMethod::Select	Creates the IM window and image list.
IInputMethod::SetImData	Responds to a request from an application to set IM-specific data within the IM.
IInputMethod::Showing	Performs any initialization before the software-based input panel window is displayed.
IInputMethod::UserOptionsDlg	Presents an IM-specific options dialog box.
IInputMethod2::Deselect	Destroys its window and performs IM-specific cleanup procedures.
IInputMethod2::GetImData	Sends data from the current IM to the current application.
IInputMethod2::GetInfo	Requests data regarding the new IM, including property flags and the preferred IM size.
IInputMethod2::Hiding	Performs any saving routines before the software-based input panel is hidden.
IInputMethod2::ReceiveSipInfo	Sends the IM data about the size, placement, and docked status that the IM should use.
IInputMethod2::RegisterCallback	Provides the IM with a pointer to the IIMCallbackinterface.
IInputMethod2::RegisterCallback2	Provides the IM with a pointer to the IIMCallback2interface.
IInputMethod2::Select	Creates the IM window and image list.
IInputMethod2::SetImData	Responds to a request from an application to set IM-specific data within the IM.
IInputMethod2::SetIMMActiveContext	Receives the current state of the IME.
IInputMethod2::Showing	Performs any initialization before the software-based input panel window is displayed.
IInputMethod2::UserOptionsDlg	Presents an IM-specific options dialog box.

After the software-based input panel calls these methods, the IM should render the software-based input panel window space and respond to user actions. For more information about programming the IM, see Programming Input Methods.

An application that uses the software-based input panel should know the state of the software-based input panel — whether the panel is visible, whether it is docked, or floating, and its size and position. All of this data is stored in the SIPINFOstructure, which is accessed through the SipGetInfoand SipSetInfofunctions. The following code example shows how to use the SipGetInfoand SipSetInfofunctions to access and modify the SIPINFOstructure.

	Copy Code
BOOL LowerSip( void ) { BOOL fRes = FALSE; SIPINFO si; memset (&si, 0, sizeof (si)); si.cbSize = sizeof (si); if (SipGetInfo(&si)) { si.fdwFlags &= ~SIPF_ON; fRes = SipSetInfo(&si); } return fRes; }

When the user changes the state of the software-based input panel, the OS sends out a WM_SETTINGCHANGEmessage to all of the active applications. This wParam parameter of this message is the value SPI_SETSIPINFO in its wParamparameter. The following code example shows how you can use the SipGetInfofunction to move the software-based input panel on the screen in response to a WM_SETTINGCHANGE message.

	Copy Code
WndProc (HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam) { SIPINFO si; switch (msg) { case WM_SETTINGCHANGE: switch (wParam) { case SPI_SETSIPINFO: memset (&si, 0, sizeof (si)); si.cbSize = sizeof (si); if (SipGetInfo(&si)) { MoveWindow ( hwnd, si.rcVisibleDesktop.left, si.rcVisibleDesktop.top, si.rcVisibleDesktop.right - si.rcVisibleDesktop.left, si.rcVisibleDesktop.bottom - si.rcVisibleDesktop.top, TRUE); } break; } break; } return 0; }

Copy Code

WndProc (HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam)
{
   SIPINFO si;

   switch (msg) 
   {
	case WM_SETTINGCHANGE:
		 switch (wParam) 
		{
			case SPI_SETSIPINFO:
			 memset (&si, 0, sizeof (si));
			 si.cbSize = sizeof (si);

			 if (SipGetInfo(&si)) 
			 {
				MoveWindow (
				hwnd,
				si.rcVisibleDesktop.left,
				si.rcVisibleDesktop.top,
				si.rcVisibleDesktop.right -
si.rcVisibleDesktop.left,
				si.rcVisibleDesktop.bottom -
si.rcVisibleDesktop.top,
				TRUE);
			 }
			 break;
		 }
		 break;
   }
  return 0;
}

A change in the active IM sends messages to all of the top-level applications that are registered to receive IM notifications. Typically, the messages go to an application that controls a display, such as a taskbar. The following table shows the messages.

Event	Windows Embedded CE message	Application action
Size or position of IM changes	WM_IM_INFO	Return 0 if the application processes the message.
IM has a new icon to associate with its current state	WM_IM_INFO	Return 0 if the application processes the message.

To modify SIP properties such as the window display size, position, and window state, you can call IIMCallback::SetImInfoand pass it a pointer to an IMINFOstructure containing the desired IM settings. This callback allows the SIP to adjust its window display size when the operating system (OS) is creating the IM. If this callback is not made, the OS will use default values for these properties when creating the SIP.

See Also

Other Resources