SHSipPreference (Compact 2013)

3/28/2014

This function requests a change of position for the software-based input panel (SIP).

Syntax

BOOL SHSipPreference(
  HWND hwnd,
  SIPSTATE st
);

Parameters

• hwnd
  [in] Handle to the window requesting the desired SIP position.

• st
  [in] Specifies the requested position for the SIP. The following table shows the allowable values for this parameter.

  Value	Description
  SIP_UP	A request to display the SIP. Any pending SIP_DOWN requests are ignored.
  SIP_DOWN	A request to the SIP. When this value is used, a timer is set and the SIP is lowered only after the timer message is received. This approach prevents the SIP from flashing when one control requests SIP_DOWN and another control immediately requests SIP_UP.
  SIP_FORCEDOWN	Forces the SIP to be hidden immediately, without setting a timer. Use this value if you want the SIP hidden and are sure there will be no SIP_UP requests. This would be appropriate if, for example, your application is a full-screen game.
  SIP_UNCHANGED	Tells the system to ignore any pending down requests. If SHSipPreference is called with the SIP_DOWN flag, the system sets a timer and after the timer fires, the SIP is lowered. However, if you call SIP_UNCHANGED before the timer fires, then the SIP will stay in its current location.

Return Value

This function returns TRUE if it is successful and FALSE if it fails.

Remarks

This function is generally used by controls to position the SIP when the focus changes. Any control that requests SIP_UP should, at some point, request SIP_DOWN. This is generally done generally when the focus is lost.

The following code example shows how to use the SHSipPreference function in code that might be part of a custom control.

case WM_SETFOCUS:
  SHSipPreference(hwnd, SIP_UP);
  break;
case WM_KILLFOCUS:
  SHSipPreference(hwnd, SIP_DOWN);
  break;

Requirements

Header	aygshell.h
Library	aygshell.lib

See Also

Reference

Shell Functions