WTL ExplorerBar

• Download demo project - 114 Kb
• Download demo project source- 531 Kb
• Download wrapper source - 4.16 Kb

Introduction

Some time ago, I found the excellent control "XP style Explorer Bar" that has been presented here on CodeProject as well as on the site of Ingo A. Kubbilun, who created this control. What makes it so special and different to the other (c++) implementations available in the net is the fact that,

1. it is released as freeware
2. it can be downloaded with full source code

and best of all, it provides full theme awareness!

This makes it a perfect starter to be implemented into any project.

The fact, that ExplorerBar does not depend on MFC or any other additional library makes it a true light component, that fits perfectly into any WTL project.

Background

Users should keep in mind, that this is a wrapper around the existing control created by Ingo A. Kubbilun. A profound knowledge of the original documentation is usually the precondition for the successful use of any wrapper class.

Using the code

This wrapper class has to be used like any other of it's kind within the WTL framework:

1. Include the header file to the Frame or View:

   #include "wtl_explorerbar.h"

   Remarks:

   You need to assure, that the files "explorerbar.h" and "shellstyle.h" from the original source are within the same folder as "wtl_explorerbar.h". Additionally, the correct DLL (coming from the explorerbar source, too) has to be present either in the same directory (which is preferred), or can be found within the standard system DLL search path.

2. Insert a member variable at the right position (either Frame or View):

   lwt::wtlExplorerBar exbar_;

3. In the OnCreate method of the Frame/ View:
   1. Create the control:

      LRESULT OnCreate(LPCREATESTRUCT lpCreateStruct)
      {                                
      // Assert, that libraries are present
      bool bRes = exbar_.InitLibrary();
      ATLASSERT(bRes); 
      
      // Create the control...
      exbar_.Create(*this, rcDefault, WS_CHILD
                                    | WS_VISIBLE
                                    | WS_CLIPSIBLINGS
                                    | WS_CLIPCHILDREN);

   2. Insert Panes:

      exbar_.AddPane(IDD_PANE_PROJECT, _T("Project")
                                     , CHS_FOCUSRECT
                                     | CHS_NOSETFOCUSONCLICK
                                     | CHS_TOOLTIP
                                     | CHS_PLAYSOUND
                                     | CHS_ANIMATEFADE
                                     , MAKEINTRESOURCE(IDD_PANE_PROJECT)
                                     , *this);
      
      exbar_.AddPane(IDD_PANE_PAGE, _T("Page")
                                  , CHS_FOCUSRECT
                                  | CHS_NOSETFOCUSONCLICK
                                  | CHS_TOOLTIP
                                  | CHS_PLAYSOUND
                                  | CHS_ANIMATEFADE
                                  , MAKEINTRESOURCE(IDD_PANE_PAGE)
                                  , *this);

4. Add message handler macros to the message map of the Frame / View:

   // This is standard
   BEGIN_MSG_MAP(thisClass)
     MSG_WM_CREATE(OnCreate)
     MSG_WM_SIZE(OnSize)
   
     // ExplorerBar message handling starts here
     BEGIN_EXPLORERBAR_RELAY_HANDLER()
   
       // handlers of 1. pane
       BEGIN_PANE_RELAY_HANDLER(IDD_PANE_PROJECT)
         RELAY_MESSAGE_HANDLER(WM_INITDIALOG, OnPaneInitDialog_Project)
         RELAY_COMMAND_ID_HANDLER(IDC_PROJECT_NEW, OnClick_Project_New)
         RELAY_COMMAND_ID_HANDLER(IDC_PROJECT_OPEN, OnClick_Project_Open)
         RELAY_COMMAND_ID_HANDLER(IDC_PROJECT_SAVE, OnClick_Project_Save)
       END_PANE_RELAY_HANDLER()
   
       // handlers of 2.pane
       BEGIN_PANE_RELAY_HANDLER(IDD_PANE_PAGE)
         RELAY_MESSAGE_HANDLER(WM_INITDIALOG, OnPaneInitDialog_Page)
         RELAY_COMMAND_ID_HANDLER(IDC_PAGE_ADD, OnClick_Page_Add)
         RELAY_COMMAND_ID_HANDLER(IDC_PAGE_DELETE, OnClick_Page_Delete)
       END_PANE_RELAY_HANDLER()
       
     // End of ExplorerBar message handling
     END_EXPLORERBAR_RELAY_HANDLER()
     
     // standard again
     CHAIN_MSG_MAP(baseClass)
     
   END_MSG_MAP()

   Remark:

   All standard kinds of message handler macros are available for the WTL ExplorerBar:

   #define RELAY_MESSAGE_HANDLER(msg, func)
   #define RELAY_MESSAGE_RANGE_HANDLER(msgFirst, msgLast, func)
   #define RELAY_NOTIFY_HANDLER(id, cd, func)
   #define RELAY_NOTIFY_CODE_HANDLER(cd, func)
   #define RELAY_NOTIFY_ID_HANDLER(id, func)
   #define RELAY_NOTIFY_RANGE_HANDLER(idFirst, idLast, func)
   #define RELAY_COMMAND_HANDLER(id, cd, func)
   #define RELAY_COMMAND_CODE_HANDLER(cd, func)
   #define RELAY_COMMAND_ID_HANDLER(id, func)
   #define RELAY_COMMAND_RANGE_HANDLER(idFirst, idLast, func)

5. Add the needed message handler function definitions & declarations to your project.

   Remark:

   These message handler functions have to be defined as follows:

   LRESULT MessageHandler(UINT nMsg, WPARAM wParam, 
          LPARAM lParam, HWND hWndDlg, UINT uPaneId, BOOL& bHandled);
   LRESULT NotifyHandler(int idCtrl, LPNMHDR pnmh, HWND hwndDlg, 
                               UINT uPaneId, BOOL& bHandled);
   LRESULT CommandHandler(WORD wNotifyCode, WORD wID, HWND hWndCtl, 
                  HWND hWndDlg, UINT uPaneId, BOOL& bHandled);

6. Implement the defined message handler functions according to your needs.

   Points of Interest

   The demo project uses the way to wrap DLL functions, that has once been presented on CodeProject by Yao Zhifeng. Thanks for sharing such ideas.

   Revision History

   20050324        v1.0        Initial public release

   Licensing Information

   WTL ExplorerBar is © 2005 Ralph-D. Wetzel, 88400 Biberach, Germany. All rights reserved.

   The provided code is free for personal and commercial use, providing the copyright notice remains intact and all eventual changes are clearly marked with comments.

   Disclaimer:

   This code is provided "as is" and any expressed or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the author or any contributor be liable for any direct, indirect, incidental, special, exemplary, or consequential damage (including, but not limited to, procurement of substitute goods or services, loss of use, data or profits, or business interruption).