HOWTO: Support Toolbar Item Text in a Shell Namespace Extension

• Microsoft Win32 Software Development Kit (SDK)

SUMMARY

When implementing a shell namespace extension, the shell view can add items to the browser window's toolbar using IShellBrowser::SetToolbarItems. Previous to Internet Explorer 4.0, this toolbar could not display text for the buttons that were added. However, it would display the button's text in a ToolTip when the mouse rests on one of the toolbar items. Starting with Internet Explorer 4.0, the user has the additional option of displaying the toolbar item's text inside the button.

MORE INFORMATION

Previous to Internet Explorer 4.0, the text for the toolbar item was only displayed in a ToolTip. To facilitate this, the browser forwarded the TTN_NEEDTEXT notification to the view window to obtain the text to be displayed in the ToolTip. Internet Explorer version 4.0 and later allows existing shell namespace extensions to use the same TTN_NEEDTEXT notification, and thereby support the display of text inside the toolbar button without modification.

IMPORTANT NOTE: In versions previous to Internet Explorer 4.0 on Windows NT, the shell always sends a TTN_NEEDTEXTW notification to obtain the text. Because of this, you need to handle the TTN_NEEDTEXTW and TTN_NEEDTEXTA notifications separately. This ensures that your extension will work correctly on all platforms.

When Internet Explorer 4.0 needs to obtain the text for toolbar items, it sends the shell view window a TTN_NEEDTEXT notification to retrieve the text. Because of this, you need to supply the toolbar item text using this notification. Do not use the TB_ADDSTRING message to add text to the browser's toolbar, because your extension will not work correctly in previous versions of the shell. The browser will ignore the TB_ADDSTRING message.

If you are using MFC, another problem occurs. When the browser object sends the TTN_NEEDTEXT notification, it sets the hwndFrom member of the NMHDR structure to NULL. MFC's CWnd::OnWndMsg function looks for WM_NOTIFY messages and does not propagate them if hwndFrom is NULL. To avoid this problem, you need to override your CWnd::OnWndMsg for this specific case. See CWnd::OnWndMsg in wincore.cpp for more information. Following is an example of how to override this:

   BOOL CShellViewWnd::OnWndMsg(
      UINT message,
      WPARAM wParam,
      LPARAM lParam,
      LRESULT* pResult)
   {
   if(WM_NOTIFY == message)
      {
      LPNMHDR  pNMHDR = (LPNMHDR)lParam;

      if((NULL == pNMHDR->hwndFrom) && (TTN_NEEDTEXT == pNMHDR->code))
         {
         return OnNotify(wParam, lParam, &lResult);
         }
      }

   return CWnd::OnWndMsg(message, wParam, lParam, pResult);
   }

Keywords          : KBShell
Version           : WINNT:
Platform          : winnt
Issue type        : kbhowto