Programming a Software-Based Input Panel (Windows Embedded CE 6.0)

Article
01/05/2012

1/6/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 IInputMethod and IInputMethod2 interfaces. 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 IInputMethod and IInputMethod2 interfaces.

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 IIMCallback interface.
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 IIMCallback interface.
IInputMethod2::RegisterCallback2	Provides the IM with a pointer to the IIMCallback2 interface.
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 SIPINFO structure, which is accessed through the SipGetInfo and SipSetInfo functions. The following code example shows how to use the SipGetInfo and SipSetInfo functions to access and modify the SIPINFO structure.

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_SETTINGCHANGE message to all of the active applications. This wParam parameter of this message is the value SPI_SETSIPINFO in its wParam parameter. The following code example shows how you can use the SipGetInfo function to move the software-based input panel on the screen in response to a WM_SETTINGCHANGE message.

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::SetImInfo and pass it a pointer to an IMINFO structure 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.

Share via

Programming a Software-Based Input Panel (Windows Embedded CE 6.0)

See Also

Other Resources

Additional resources