How to use the WTL multipane status bar control

• Download Status Bar project - 8 Kb
• Download Status Bar executable - 10 Kb

Introduction

This article explains how to use WTL's CMultiPaneStatusBarCtrl class in an application. The sample project included with this article is a wizard-generated SDI application enhanced with a three pane status bar that displays status messages and the current date and time.

Status Bar

All of the relevant code for using the status bar is contained in the mainframe.h file of the sample project. The status bar is initialized in the OnCreate method, which also calls a workaround for a bug in the WTL class. Another method provides a timer handler and is used to display date and time in status bar panes.

Basics

A status bar provides users with various types of feedback and information as they use an application. WTL wizard-generated applications define a single pane status bar. It handles the basic functions of showing "Ready" and is switched to simple mode to display menu tips. Multipane status bars, on the other hand, are divided into multiple, independently controlled segments.

Initialization

Please note that you must include the atlctrlx.h header file. It defines the CMultiPaneStatusBarCtrl class. You must also include atlmisc.h, as it defines AtlLoadIconImage() and the CString class.

The following steps are needed to define and initialize a multipane status bar control for an application:

1. Create a resource definition for each status bar pane
2. Define a member variable: CMultiPaneStatusBarCtrl m_status;
3. Subclass the "simple" status bar created by the WTL wizard
4. Enumerate and set the status bar panes
5. Call the workaround method, SetPaneWidths()
6. Set the icons (if desired) for the individual status bar panes

The following resource definitions from resource.h pertain to the status bar panes and their icons. They were created by the resource editor when the icons were imported and they are used to identify status bar panes as well as the icons. You must manually enter similar values if you do not import or create status bar icons for your application.

#define IDR_DEFAULT 201
#define IDR_DATE    202
#define IDR_TIME    203

In addition, WTL defines a default pane identifier, ID_DEFAULT_PANE, which it uses as a variable width pane for status messages such as "Ready".

Here is the OnCreate() method from mainframe.h. Note that the width of the default pane is set to 0 in the array passed to SetPaneWidths().

LRESULT OnCreate(UINT, WPARAM, LPARAM, BOOL&)
{ 
    CreateSimpleStatusBar();

    // subclass the status bar as multipane
    m_status.SubclassWindow(m_hWndStatusBar);

    // set status bar panes. ID_DEFAULT_PANE is defined by WTL
    int arrPanes[] = { ID_DEFAULT_PANE, IDR_DATE, IDR_TIME };

    m_status.SetPanes(arrPanes, 
        sizeof(arrPanes) / sizeof(int), false);

    // set status bar pane widths using local workaround
    int arrWidths[] = { 0, 90, 60 };
    SetPaneWidths(arrWidths, sizeof(arrWidths) / sizeof(int));

    // set the status bar pane icons
    m_status.SetPaneIcon(ID_DEFAULT_PANE, 
        AtlLoadIconImage(IDR_DEFAULT, LR_DEFAULTCOLOR));

    m_status.SetPaneIcon(IDR_DATE, 
        AtlLoadIconImage(IDR_DATE, LR_DEFAULTCOLOR));

    m_status.SetPaneIcon(IDR_TIME, 
        AtlLoadIconImage(IDR_TIME, LR_DEFAULTCOLOR));

    // initialize date/time and start a 1 second timer
    OnTimer(0, 0, 0, bHandled);
    SetTimer(1, 1000);

    return 0; 
}

Workaround

SetPaneWidths() is a workaround that solves a bug in the CMultiPaneStatusBarCtrl::SetPanes() method. The bug limits the width of all panes after the default pane to a combined total of 100 pixels. This workaround allows arbitrary pane widths.

void SetPaneWidths(int* arrWidths, int nPanes)
{ 
    // find the size of the borders
    int arrBorders[3];
    m_status.GetBorders(arrBorders);

    // calculate right edge of default pane (0)
    arrWidths[0] += arrBorders[2];
    for (int i = 1; i < nPanes; i++)
        arrWidths[0] += arrWidths[i];

    // calculate right edge of remaining panes (1 thru nPanes-1)
    for (int j = 1; j < nPanes; j++)
        arrWidths[j] += arrBorders[2] + arrWidths[j - 1];

    // set the pane widths
    m_status.SetParts(m_status.m_nPanes, arrWidths); 
}

Timer Handler

Here is the code for the timer handler. You must also create a message map entry for the WM_TIMER message.

LRESULT OnTimer(UINT, WPARAM, LPARAM, BOOL&)
{ 
    // get the current date and time
    SYSTEMTIME st;
    ::GetLocalTime(&st);

    CString str;

    // Pane 1: Display the date
    str.Format("%i/%i/%i", st.wMonth, st.wDay, st.wYear);
    m_status.SetPaneText(IDR_DATE, str);

    // Pane 2: Display the time
    str.Format("%i:%02i", st.wHour, st.wMinute);
    m_status.SetPaneText(IDR_TIME, str);

    return 0; 
}

Terms Of Use

The sample application available with this article is free for any purpose.

THIS SOFTWARE IS DISTRIBUTED AS-IS, WITHOUT WARRANTIES OF ANY KIND.