Controlling the SIP

  • Article

SHSipInfo is an omnibus function that lets you control the soft keyboard. On the Pocket PC, SHSipInfo has limited usefulness because most applications should use SHSipPreference instead of SHSipInfo. Still, SHSipInfo is handy because it is the only way to query the state and location of the SIP. It also allows an application to change the default input method. The function is prototyped as

BOOL SHSipInfo (UINT uiAction, UINT uiParam, PVOID pvParam,
                UINT fWinIni);

The first parameter to SHSipInfo, uiAction, should be set with a flag that specifies the action you want to perform with the function. The allowable flags are

SPI_SETSIPINFO

  • Sets the SIP configuration including its location and its visibility (Obsolete. Use SHSipPreference.)

SPI_GETSIPINFO

  • Queries the SIP configuration

SPI_SETCURRENTIM

  • Sets the current default input method

SPI_GETCURRENTIM

  • Queries the current default input method

Because the behavior of SHSipInfo is completely different for each of the flags, I'll describe the function as if it were three different function calls. I won't discuss SPI_SETSIPINFO because its function is superseded by SHSipPreference. For each of the flags, the second and fourth parameters, uiParam and fWinIni, must be set to 0.

Querying the State of the SIP

To query the current state of the SIP, call SHSipInfo with the SPI_GETSIPINFO flag in the uiAction parameter. In this case, the function looks like this:

BOOL SHSipInfo (SPI_GETSIPINFO, 0, SIPINFO *psi, 0);

The third parameter must point to a SIPINFO structure, which is defined as

typedef struct {
    DWORD cbSize;
    DWORD fdwFlags;
    RECT rcVisibleDesktop;
    RECT rcSipRect;
    DWORD dwImDataSize;
    VOID *pvImData;
} SIPINFO;

The structure's first field, cbSize, must be set to the size of the SIPINFO structure before a call is made to SHSipInfo. The second field in SIPINFO, fdwFlags, can contain a combination of the following flags:

SIPF_ON

  • When set, the SIP is visible.

SIPF_DOCKED

  • When set, the SIP is docked to its default location on the screen.

SIPF_LOCKED

  • When set, the visibility state of the SIP can't be changed by the user.

The next two fields of SIPINFO provide information on the location of the SIP. The field rcVisibleDesktop is filled with the screen dimensions of the visible area of the desktop. If the SIP is docked, this area is the rectangle above the SIP. If the SIP is undocked, this rectangle contains the full desktop area minus the taskbar, if the taskbar is showing. This field is ignored when you set the SIP configuration. Some SIPs might have a docked state that doesn't run from edge to edge of the screen. In this case, the rectangle describes the largest rectangular area of the screen that isn't obscured by the SIP.

The rcSipRect field contains the location and size of the SIP. If the SIP is docked, the rectangle is usually the area of the screen not included by rcVisibleDesktop. But if the SIP is undocked, rcSipRect contains the size and position of the SIP while rcVisibleDesktop contains the entire desktop not obscured by the taskbar, including the area under the SIP. Figure 17-6 shows the relationship between rcVisibleDesktop and rcSipRect.

Figure 17-6

The relationship between rcVisibleDesktop and rcSipRect in the SIPINFO structure

The final two fields of SIPINFO allow you to query information specific to the current input method. The format of this information is defined by the input method. To query this information, set the pvImData field to point to a buffer to receive the information and set dwImDataSize to the size of the buffer. It is up to the application to know which input methods provide what specific data. For most input methods, these two fields should be set to 0 to indicate that no IM-specific data is being queried.

Changing the Default Input Method

You can use SHSipInfo to query and to change the current SIP. To query the current SIP, you call SHSipInfo with the SPI_GETCURRENTIM flag in the uiAction parameter, as in

BOOL SHSipInfo (SPI_GETCURRENTIM, 0, CLSID *pclsid, 0);

In this case, the third parameter points to a CLSID variable that receives the CLSID of the current input method.

To set the current input method, call SHSipInfo with the uiAction parameter set to SPI_SETCURRENTIM, as in

BOOL SHSipInfo (SPI_SETCURRENTIM, 0, CLSID *pclsid, 0);

Here again, the third parameter of SHSipInfo is a pointer to a CLSID value. In this case, the value must contain a CLSID of a valid input method.

This chapter has covered a fair amount of ground. However, the Pocket PC is more than applications. It's possible to extend the basic shell of the Pocket PC in a number of ways. In the next chapter, we'll extend the Today screen and create a new input method for the SIP.

This topic is from Programming Microsoft Windows CE, Third Edition, by Douglas Boling, published by Microsoft Press. © 2003 by Douglas McConnaughey Boling. Reprinted here by permission of the author.