Soft Keys

4/8/2010

Windows Mobile provides support for soft keys. Soft keys display menus and commands when you press corresponding hardware buttons on Windows Mobile devices. The soft keys are located on the soft key bar at the bottom of the screen.

Note

Beginning with Windows Mobile 6.5.3, soft keys are replaced by touchable tiles on Windows Mobile Professional phones.

The right soft key displays a menu and the left soft key provides access to the most common action based on the content that is currently displayed or selected. All Microsoft applications use soft keys on Windows Mobile. Support is provided for customizing soft keys in the following ways.

  • You can change the command associated with a soft key to correspond to changes on the screen. For example, in the Contacts application, the command associated with the left soft key changes from New to Edit when you select a specific contact.
  • You can modify the default handling of key messages sent to a soft key or receive notification of these messages by using the SHCMBM_OVERRIDEKEY message.

Soft keys support many toolbar messages, listed below. For more information about these messages, see Toolbar Controls Messages.

Toolbar Message Windows Mobile Professional or Windows Mobile Classic Windows Mobile Standard Description

TB_ADDBITMAP

X

 

Causes the softkey bar to change to a toolbar.

TB_ADDBUTTONS

X

 

Causes the softkey bar to change to a toolbar if the total number of buttons exceeds 2.

TB_ADDSTRING

X

 

 

TB_AUTOSIZE

X

X

Does not do anything, but returns 1.

TB_BUTTONCOUNT

X

 

 

TB_BUTTONSTRUCTSIZE

X

 

On Windows Mobile Classic, passing the old TBBUTTON struct size in wParam (which does not contain dwData or iString) to a softkey bar with 0 buttons will cause the softkey bar to change to a toolbar.

TB_CHANGEBITMAP

X

X

Does not do anything, but returns 0 to indicate false or error.

TB_CHECKBUTTON

X

X

Does not draw a visual check mark but the state is saved.

TB_COMMANDTOINDEX

X

X

 

TB_DELETEBUTTON

X

 

Remaining buttons are shuffled down (i.e. if button at index 0 is deleted then button at index 1 moves to index 0).

TB_ENABLEBUTTON

X

X

 

TB_GETBITMAP

X

X

Does not do anything, but returns 0 to indicate false or error.

TB_GETBITMAPFLAGS

X

X

Does not do anything, but returns 0 to indicate false or error.

TB_GETBUTTON

X

X

 

TB_GETBUTTONINFO

X

X

 

TB_GETBUTTONSIZE

X

X

 

TB_GETBUTTONTEXT

X

 

 

TB_GETDISABLEDIMAGELIST

X

X

Does not do anything, but returns 0 to indicate false or error.

TB_GETIMAGELIST

X

X

Does not do anything, but returns 0 to indicate false or error.

TB_GETITEMRECT

X

X

 

TB_GETRECT

X

X

 

TB_GETROWS

X

X

Does not do anything, but returns 1.

TB_GETSTATE

X

X

 

TB_GETSTYLE

X

X

Softkeys always return (TBSTYLE_LIST | TBSTYLE_TRANSPARENT | TBSTYLE_FLAT | CCS_BOTTOM | CCS_NOMOVEY | CCS_NORESIZE)

TB_GETTEXTROWS

X

X

Does not do anything, but returns 1.

TB_GETTOOLTIPS

X

X

Does not do anything, but returns 0 to indicate false or error.

TB_HIDEBUTTON

X

X

 

TB_HIGHLIGHTBUTTON

X

X

Does not do anything, but returns 1.

TB_INDETERMINATE

X

X

Does not do anything, but returns 1.

TB_INSERTBUTTON

X

 

Causes the softkey bar to change to a toolbar if the total number of buttons exceeds 2.

TB_ISBUTTONCHECKED

X

X

 

TB_ISBUTTONENABLED

X

X

 

TB_ISBUTTONHIDDEN

X

X

 

TB_ISBUTTONHIGHLIGHTED

X

X

Does not do anything, but returns 1.

TB_ISBUTTONINDETERMINATE

X

X

Does not do anything, but returns 1.

TB_ISBUTTONPRESSED

X

X

Does not do anything, but returns 1.

TB_LOADIMAGES

X

 

Causes the softkey bar to change to a toolbar.

TB_PRESSBUTTON

X

X

Does not do anything, but returns 1.

TB_REPLACEBITMAP

X

X

Does not do anything, but returns 1.

TB_SETBITMAPSIZE

X

 

Causes the softkey bar to change to a toolbar.

TB_SETBUTTONINFO

X

X

TBIF_STYLE styles are ignored. On Windows Mobile Professional and Windows Mobile Classic, they are saved in case the softkey bar changes to a toolbar. Setting an image or separator will cause the softkey bar to change to a toolbar.

TB_SETBUTTONSIZE

X

X

Does not do anything, but returns 1.

TB_SETBUTTONWIDTH

X

X

Does not do anything, but returns 1.

TB_SETCMDID

X

X

 

TB_SETDISABLEDIMAGELIST

X

 

Causes the softkey bar to change to a toolbar

TB_SETDRAWTEXTFLAGS

X

X

Does not do anything, but returns 1.

TB_SETIMAGELIST

X

 

Causes the softkey bar to change to a toolbar

TB_SETINDENT

X

X

Does not do anything, but returns 1.

TB_SETMAXTEXTROWS

X

 

Causes the softkey bar to change to a toolbar if iMaxRows (wParam) is larger than 1, otherwise TRUE is returned and nothing is changed.

TB_SETPARENT

X

 

 

TB_SETROWS

X

 

Causes the softkey bar to change to a toolbar if cRows (HIWORD of wParam) is larger than 1.

TB_SETSTATE

X

X

 

TB_SETSTYLE

X

 

Causes the softkey bar to change to a toolbar if dwStyle (lParam) has the TBSTYLE_WRAPABLE or TBSTYLE_CUSTOMERASE, otherwise 1 is returned and nothing is changed.

TB_SETTOOLTIPS

X

X

Does not do anything, but returns 1.

In This Section

  • Dynamic Assignment of SK1
    Demonstrates how to dynamically change the left soft key to correspond to the most recent event on the device.
  • User Interface
    Provides information on the ways that a user can interact with a Windows Mobile device and its applications.