Programming Microsoft Windows Ce Net 3Rd [Electronic resources] نسخه متنی

Additional Pocket PC Shell Functions

The Pocket PC has a few functions provided to support applications. Most of these functions are unique to the Pocket PC and are available to solve specific issues that Pocket PC applications need to deal with occasionally. These functions are also available on embedded systems that support the aygshell component but their implementation is OEM specific.

Full-Screen Windows

The SHFullScreen function allows an application to control the visibility of items such as the Start icon on the navigation bar, the navigation bar itself, and the SIP button. The function is prototyped as

BOOL SHFullScreen (HWND hwndRequester, DWORD dwState);

The first parameter is the handle of the window requesting the change. The dwState parameter can be a combination of the following:

SHFS_HIDETASKBARHide the navigation bar.

SHFS_SHOWTASKBARShow the navigation bar.

SHFS_HIDESIPBUTTONHide the SIP button on the menu bar.

SHFS_SHOWSIPBUTTONShow the SIP button on the menu bar.

SHFS_HIDESTARTICONHide the Windows icon on the navigation bar. This disables the Start menu.

SHFS_SHOWSTARTICONShow the Windows icon on the navigation bar. This enables the Start menu.

The flags that hide the navigation bar, the SIP button, and the Start icon can be passed only if the handle passed in the first parameter of SHFullScreen is the handle to the foreground window.

Freeing Memory

Another handy function allows an application to request that the system free a specified amount of memory so that memory can be allocated. The function is

BOOL SHCloseApps (DWORD dwMemSought);

This parameter is the amount of memory that the application needs. When this function is called, the Pocket PC checks the current memory state to determine whether the amount of memory requested is available. If so, the function returns immediately. If not, the Pocket PC uses various methods, including closing applications, to attempt to free that amount of memory. SHCloseApps will return TRUE if the amount of memory is available and FALSE if it could not free the amount requested. Because this function closes applications and therefore must wait for each application to properly shut down, it can take a few seconds to complete.

Controlling the SIP

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.

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.

Figure 17-6: The relationship between rcVisibleDesktop and rcSipRect in the SIPINFO structure

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.