Share via

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.

Comments

  • Anonymous
    May 02, 2007
    Is there any way (from managed code, but I'm not afraid of interop :-) ) to programmatically  trigger a Softkey tap? Sane people are likely thinking "Why would you want to do that instead of just calling directly the method you call from the event handler?", so I will explain. We are currently (in my boring day job) trying out dataloggers that are running Windows Mobile 5, but the hardware OEM has not mapped any of the hardware keys or buttons (there are lots) to anything that WM5 recognises as a button, so it is not possible to map the Softkeys to hardware buttons... which is a great shame (we would like to provide our users a stylus-free experience as much as possible). So, what we would like to do is within the application trap button presses and then trigger the relevant Softkey programmatically, so that it works from the user's point of view as if the button was mapped to the Softey. Any information on whether this is possible and how it could be done would be greatly appreciated.

  • Anonymous
    May 02, 2007
    The comment has been removed

  • Anonymous
    May 08, 2007
    Hi, When I use SHAddNotification() to add an icon to title-bar is there any way NOT to have my notifcation take control of the Left soft-key (changing it to "Notification")? I want it to leave the standard left soft-key function and text. Thanks.

  • Anonymous
    May 10, 2007
    Are there any samples in Vb of setting up soft keys? It should be so easy!

  • Anonymous
    May 23, 2007
    see here about issues on menu on PPC and SP. If someone knows how to solve this issue : Menu creation PPC SPV http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=1636652&SiteID=1

  • Anonymous
    July 12, 2007
    well, this question is maybe trivi and it's not really focused on developement - but you seems to be the only capable of qualified reply: is there any easy way to remove softkeys completely from today screen on wm5/6? i'm never using them, so some registry or dll tweaking will be very helpful and will help to get more space on today screen... Regards jaromir kokes

  • Anonymous
    July 18, 2007
    I only have one request and I'm not even sure if Pat is the one to answer it, but here goes. I recently installed a copy of Windows Mobile 6 and my one major complaint is the left softkey in the inbox is assigned to Delete. All I would like to do is swap it to "New" so that I could use the softkey to immediately open a new message ala Windows Mobile 5. Any assistance you could provide suggesting how to tweak this would be immensely appreciated.

  • Anonymous
    October 02, 2007
    I've looked everywhere and cannot figure out how to implement separators between soft key menu items. Any help is of course appreciated.

  • Anonymous
    October 02, 2007
    The comment has been removed

  • Anonymous
    January 11, 2008
    I have softkey loaded with a dialog screen on PPC, pressed the key will create another dialogue window. However, when the new dialogue window is closed. The softkey does not react anymore. What should I do to let it work again?

  • Anonymous
    May 13, 2008
    I'm developing a win32 application on the windows mobile 5.0 using C++. I need to program the soft keys but I can't find a good tutorial to do that. Can anybody help? Thanks

  • Anonymous
    May 20, 2008
    Patrick, We are connected a WM device to a larger screen and we notice that often the menu bar loses it's gradient and just gets painted with  flat color. We also noticed that if we use the right sequence of launching applications and notifications the menu bar will start showing the gradient fill again. Once it starts showing the gradient fill it keeps showing it until we do a soft reset on the phone. Is there some message or call we can invoke that would get the menu bar to begin displaying the gradient? Thanks in advance for your response.

  • Anonymous
    June 12, 2008
    Patrick, I have made some simple Mainframe/CView applications with a pop-up menu in the command bar and I have noticed that everytime that I open the pop-up menu (Softkey 1 or 2) and I get 2 "Data Abort" error by gwes.exe.   When I close the pop-up menu however I do not get these errors. When I recreate these applications based on dialogs I do not get these errors. Any idea what is causing this error?

  • Anonymous
    June 12, 2008
    In regards to my "Data Abort" by gwes.exe problem: This is on the Windows Mobile Standard platform.

  • Anonymous
    June 19, 2008
    I can't get the handle of the softkeys.I don't know how to ,can you tell me ? I used the toolbar message "TB_GETBUTTON", but there is no response ,the return value is NULL.

  • Anonymous
    December 09, 2008
    Hi Patrick, I am developing an application for Windows Mobile 6, and  use SHCreateMenuBar to create a menubar to handle the soft keys. If I run my application in normal windowed mode (ie not full-screen), both WM_KEYDOWN and WM_KEYUP messages are sent to my WndProc() function when a soft key is pressed and released. However, if my application runs in full-screen mode, only a WM_KEYUP message (ie no WM_KEYDOWN) is sent to my WndProc() function. This causes problems for my application, as it needs to be able to detect when the key is pressed and released ... so I cannot simply simulate a KEYDOWN when a KEYUP is received. This behaviour is present in WM 5 and WM 6. Please can you suggest a workaround ? Is there any chance this could be fixed in WM 7 ? Many thanks, Kevin

  • Anonymous
    March 20, 2009
    Hi, I want to change the button style. For example, change it from button to pop-menu style. Could you help me to do that? coldstar

  • Anonymous
    March 31, 2009
    How can I disable the softkeys? If in a terminal emulation on WM2003/WM5/WM6.1 device to a host we often need the function keys that are mapped to Volume up/down, left/right softkey and the other function keys mapped to OS features. How can we use these function keys without the intervention of the OS? We use GXOpenInput(). But is would be better to have a option in settings to enable/disable or reassign the key codes used by the OS. Any information appreciated Josef

  • Anonymous
    April 28, 2009
    hi, i have created a toolbar at the bottom of the screen, using SHCreateMenuBar, i need to make my toolbar background transparent so that the window behind it is visible. i tried using TBSTYLE_FLAT and TBSTYLE_TRANSPARENT, but am not being able to build my code. Am I missing something, is there anything else that can be done. Thanks for any help in advance.