Hi, my name is Patrick Derks and I work as a developer in the Windows Mobile Shell. I’ve owned the softkey code in Windows Mobile for a few months now and I keep getting questions about how to do basic stuff with the softkeys. For example, I had a developer just the other day ask how they could change the label of a softkey. These sorts of questions are a good indication of just how lousy our documentation has been for softkeys and we’ve tried to rectify that in the Windows Mobile 6 SDK. If you search for “softkeys” in the SDK you should be able to find an entry with the following table detailing all the toolbar messages (TB_*) that the softkey bar supports (included below). Hopefully this will help take away some of the mystery on how to get stuff done with the softkeys.
Toolbar Message | Windows Mobile 6 Professional or Windows Mobile 6 Classic | Windows Mobile 6 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 6 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 6 Professional and Windows Mobile 6 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. |
You’ll notice in the table that for a number of the TB_* messages it mentions “changing the softkey bar to a toolbar” in the description. This automatic transformation to a toolbar was put in place in Windows Mobile 5 (WM5) when softkey support was first added for Pocket PC. Prior to WM5, Pocket PC apps all got toolbars when SHCreateMenuBar was called but in WM5 this was changed so that a softkey bar was created instead of a toolbar. In order to try and not break every Pocket PC application out there a bunch of support for TB_* messages was added to the softkeys in Pocket PC and thats why Pocket PC (excuse me, I mean Windows Mobile Professional/Classic) supports a larger set of TB_* messages than Smartphone (Windows Mobile Standard). If you ask me its kind of silly that we have different levels of support for TB_* messages for the two SKU’s and rest assured I’m working hard to rectify this for a future release.
By the way, if anybody has any questions, comments or suggestions about the softkeys in Windows Mobile I’d also be very interested to hear them.