Softkeys and you!

  • Article

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.