CToolBar Class

Control bars that have a row of bitmapped buttons and optional separators.

Syntax

class CToolBar : public CControlBar

Members

Public Constructors

Name	Description
CToolBar::CToolBar	Constructs a CToolBar object.

Public Methods

Name	Description
CToolBar::CommandToIndex	Returns the index of a button with the given command ID.
CToolBar::Create	Creates the Windows toolbar and attaches it to the CToolBar object.
CToolBar::CreateEx	Creates a CToolBar object with additional styles for the embedded CToolBarCtrl object.
CToolBar::GetButtonInfo	Retrieves the ID, style, and image number of a button.
CToolBar::GetButtonStyle	Retrieves the style for a button.
CToolBar::GetButtonText	Retrieves the text that will appear on a button.
CToolBar::GetItemID	Returns the command ID of a button or separator at the given index.
CToolBar::GetItemRect	Retrieves the display rectangle for the item at the given index.
CToolBar::GetToolBarCtrl	Allows direct access to the underlying common control.
CToolBar::LoadBitmap	Loads the bitmap containing bitmap-button images.
CToolBar::LoadToolBar	Loads a toolbar resource created with the resource editor.
CToolBar::SetBitmap	Sets a bitmapped image.
CToolBar::SetButtonInfo	Sets the ID, style, and image number of a button.
CToolBar::SetButtons	Sets button styles and an index of button images within the bitmap.
CToolBar::SetButtonStyle	Sets the style for a button.
CToolBar::SetButtonText	Sets the text that will appear on a button.
CToolBar::SetHeight	Sets the height of the toolbar.
CToolBar::SetSizes	Sets the sizes of buttons and their bitmaps.

Remarks

The buttons can act like pushbuttons, check-box buttons, or radio buttons. CToolBar objects are usually embedded members of frame-window objects derived from the class CFrameWnd or CMDIFrameWnd.

CToolBar::GetToolBarCtrl, a member function new to MFC 4.0, allows you to take advantage of the Windows common control's support for toolbar customization and additional functionality. CToolBar member functions give you most of the functionality of the Windows common controls; however, when you call GetToolBarCtrl, you can give your toolbars even more of the characteristics of Windows 95/98 toolbars. When you call GetToolBarCtrl, it will return a reference to a CToolBarCtrl object. See CToolBarCtrl for more information about designing toolbars using Windows common controls. For more general information about common controls, see Common Controls in the Windows SDK.

Visual C++ provides you with two methods to create a toolbar. To create a toolbar resource using the Resource Editor, follow these steps:

1. Create a toolbar resource.

2. Construct the CToolBar object.

3. Call the Create (or CreateEx) function to create the Windows toolbar and attach it to the CToolBar object.

4. Call LoadToolBar to load the toolbar resource.

Otherwise, follow these steps:

1. Construct the CToolBar object.

2. Call the Create (or CreateEx) function to create the Windows toolbar and attach it to the CToolBar object.

3. Call LoadBitmap to load the bitmap that contains the toolbar button images.

4. Call SetButtons to set the button style and associate each button with an image in the bitmap.

All the button images in the toolbar are taken from one bitmap, which must contain one image for each button. All images must be the same size; the default is 16 pixels wide and 15 pixels high. Images must be side by side in the bitmap.

The SetButtons function takes a pointer to an array of control IDs and an integer that specifies the number of elements in the array. The function sets each button's ID to the value of the corresponding element of the array and assigns each button an image index, which specifies the position of the button's image in the bitmap. If an array element has the value ID_SEPARATOR, no image index is assigned.

The order of the images in the bitmap is typically the order in which they're drawn on the screen, but you can use the SetButtonInfo function to change the relationship between image order and drawing order.

All buttons in a toolbar are the same size. The default is 24 x 22 pixels, in accordance with Windows Interface Guidelines for Software Design. Any additional space between the image and button dimensions is used to form a border around the image.

Each button has one image. The various button states and styles (pressed, up, down, disabled, disabled down, and indeterminate) are generated from that one image. Although bitmaps can be any color, you can achieve the best results with images in black and shades of gray.

Toolbar buttons imitate pushbuttons by default. However, toolbar buttons can also imitate check-box buttons or radio buttons. Check-box buttons have three states: checked, cleared, and indeterminate. Radio buttons have only two states: checked and cleared.

To set an individual button or separator style without pointing to an array, call GetButtonStyle to retrieve the style, and then call SetButtonStyle instead of SetButtons. SetButtonStyle is most useful when you want to change a button's style at run time.

To assign text to appear on a button, call GetButtonText to retrieve the text to appear on the button, and then call SetButtonText to set the text.

To create a check-box button, assign it the style TBBS_CHECKBOX or use a CCmdUI object's SetCheck member function in an ON_UPDATE_COMMAND_UI handler. Calling SetCheck turns a pushbutton into a check-box button. Pass SetCheck an argument of 0 for unchecked, 1 for checked, or 2 for indeterminate.

To create a radio button, call a CCmdUI object's SetRadio member function from an ON_UPDATE_COMMAND_UI handler. Pass SetRadio an argument of 0 for unchecked or nonzero for checked. In order to provide a radio group's mutually exclusive behavior, you must have ON_UPDATE_COMMAND_UI handlers for all of the buttons in the group.

For more information on using CToolBar, see the article MFC Toolbar Implementation and Technical Note 31: Control Bars.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CControlBar

CToolBar

Requirements

Header: afxext.h

CToolBar::CommandToIndex

This member function returns the index of the first toolbar button, starting at position 0, whose command ID matches nIDFind.

int CommandToIndex(UINT nIDFind) const;

Parameters

nIDFind
Command ID of a toolbar button.

Return Value

The index of the button, or -1 if no button has the given command ID.

CToolBar::Create

This member function creates a Windows toolbar (a child window) and associates it with the CToolBar object.

virtual BOOL Create(
    CWnd* pParentWnd,
    DWORD dwStyle = WS_CHILD | WS_VISIBLE | CBRS_TOP,
    UINT nID = AFX_IDW_TOOLBAR);

Parameters

pParentWnd
Pointer to the window that is the toolbar's parent.

dwStyle
The toolbar style. Additional toolbar styles supported are:

• CBRS_TOP Control bar is at top of the frame window.

• CBRS_BOTTOM Control bar is at bottom of the frame window.

• CBRS_NOALIGN Control bar isn't repositioned when the parent is resized.

• CBRS_TOOLTIPS Control bar displays tool tips.

• CBRS_SIZE_DYNAMIC Control bar is dynamic.

• CBRS_SIZE_FIXED Control bar is fixed.

• CBRS_FLOATING Control bar is floating.

• CBRS_FLYBY Status bar displays information about the button.

• CBRS_HIDE_INPLACE Control bar isn't displayed to the user.

nID
The toolbar's child-window ID.

Return Value

Nonzero if successful; otherwise 0.

Remarks

It also sets the toolbar height to a default value.

Example

// This code fragment is taken from CMainFrame::OnCreate
// CMainFrame is derived from CMDIFrameWnd.

//This example creates a dockable toolbar.
if (!m_wndToolBar.Create(this) ||
   !m_wndToolBar.LoadToolBar(IDR_MAINFRAME))
{
   TRACE0("Failed to create toolbar\n");
   return -1;      // fail to create
}

//Make the toolbar dockable
m_wndToolBar.EnableDocking(CBRS_ALIGN_ANY);
EnableDocking(CBRS_ALIGN_ANY);
DockControlBar(&m_wndToolBar);

CToolBar::CreateEx

Call this function to create a Windows toolbar (a child window) and associate it with the CToolBar object.

virtual BOOL CreateEx(
    CWnd* pParentWnd,
    DWORD dwCtrlStyle = TBSTYLE_FLAT,
    DWORD dwStyle = WS_CHILD | WS_VISIBLE | CBRS_ALIGN_TOP,
    CRect rcBorders = CRect(
    0,
    0,
    0,
    0),
    UINT nID = AFX_IDW_TOOLBAR);

Parameters

pParentWnd
Pointer to the window that is the toolbar's parent.

dwCtrlStyle
Additional styles for the creation of the embedded CToolBarCtrl object. By default, this value is set to TBSTYLE_FLAT. For a complete list of toolbar styles, see dwStyle.

dwStyle
The toolbar style. See Toolbar Control and Button Styles in the Windows SDK for a list of appropriate styles.

rcBorders
A CRect object that defines the widths of the toolbar window borders. These borders are set to 0,0,0,0 by default, thereby resulting in a toolbar window with no borders.

nID
The toolbar's child-window ID.

Return Value

Nonzero if successful; otherwise 0.

Remarks

It also sets the toolbar height to a default value.

Use CreateEx, instead of Create, when certain styles need to be present during the creation of the embedded tool bar control. For example, set dwCtrlStyle to TBSTYLE_FLAT | TBSTYLE_TRANSPARENT to create a toolbar that resembles the Internet Explorer 4 toolbars.

Example

// This example demonstrates CToolBar::CreateEx by creating a 
// toolbar as part of a child frame window. It also calls the 
// LoadToolbar and EnableDocking functions
int CChildFrame::OnCreate(LPCREATESTRUCT lpCreateStruct)
{
   if (CMDIChildWnd::OnCreate(lpCreateStruct) == -1)
      return -1;

   if (!m_wndMyToolBar.CreateEx(this, TBSTYLE_FLAT, WS_CHILD | WS_VISIBLE | CBRS_TOP
      | CBRS_GRIPPER | CBRS_TOOLTIPS | CBRS_FLYBY | CBRS_SIZE_DYNAMIC) ||
      !m_wndMyToolBar.LoadToolBar(IDR_MYTOOLBAR))
   {
      TRACE0("Failed to create toolbar\n");
      return -1;      // fail to create
   }

   m_wndMyToolBar.EnableDocking(CBRS_ALIGN_ANY);
   EnableDocking(CBRS_ALIGN_ANY);
   DockControlBar(&m_wndMyToolBar);

   return 0;
}

CToolBar::CToolBar

This member function constructs a CToolBar object and sets the default sizes.

CToolBar();

Remarks

Call the Create member function to create the toolbar window.

CToolBar::GetButtonInfo

This member function retrieves the control ID, style, and image index of the toolbar button or separator at the location specified by nIndex.

void GetButtonInfo(
    int nIndex,
    UINT& nID,
    UINT& nStyle,
    int& iImage) const;

Parameters

nIndex
Index of the toolbar button or separator whose information is to be retrieved.

nID
Reference to a UINT that is set to the command ID of the button.

nStyle
Reference to a UINT that is set to the style of the button.

iImage
Reference to an integer that is set to the index of the button's image within the bitmap.

Remarks

Those values are assigned to the variables referenced by nID, nStyle, and iImage. The image index is the position of the image within the bitmap that contains images for all the toolbar buttons. The first image is at position 0.

If nIndex specifies a separator, iImage is set to the separator width in pixels.

CToolBar::GetButtonStyle

Call this member function to retrieve the style of a button or separator on the toolbar.

UINT GetButtonStyle(int nIndex) const;

Parameters

nIndex
The index of the toolbar button or separator style to be retrieved.

Return Value

The style of the button or separator specified by nIndex.

Remarks

A button's style determines how the button appears and how it responds to user input. See SetButtonStyle for examples of button styles.

CToolBar::GetButtonText

Call this member function to retrieve the text that appears on a button.

CString GetButtonText(int nIndex) const;

void GetButtonText(
    int nIndex,
    CString& rString) const;

Parameters

nIndex
Index of the text to be retrieved.

rString
A reference to a CString object that will contain the text to be retrieved.

Return Value

A CString object containing the button text.

Remarks

The second form of this member function fills a CString object with the string text.

CToolBar::GetItemID

This member function returns the command ID of the button or separator specified by nIndex.

UINT GetItemID(int nIndex) const;

Parameters

nIndex
Index of the item whose ID is to be retrieved.

Return Value

The command ID of the button or separator specified by nIndex.

Remarks

Separators return ID_SEPARATOR.

CToolBar::GetItemRect

This member function fills the RECT structure whose address is contained in lpRect with the coordinates of the button or separator specified by nIndex.

virtual void GetItemRect(
    int nIndex,
    LPRECT lpRect) const;

Parameters

nIndex
Index of the item (button or separator) whose rectangle coordinates are to be retrieved.

lpRect
Address of the RECT structure that will contain the item's coordinates.

Remarks

Coordinates are in pixels relative to the upper-left corner of the toolbar.

Use GetItemRect to get the coordinates of a separator you want to replace with a combo box or other control.

Example

See the example for CToolBar::SetSizes.

CToolBar::GetToolBarCtrl

This member function allows direct access to the underlying common control.

CToolBarCtrl& GetToolBarCtrl() const;

Return Value

A reference to a CToolBarCtrl object.

Remarks

Use GetToolBarCtrl to take advantage of the functionality of the Windows toolbar common control, and to take advantage of the support CToolBarCtrl provides for toolbar customization.

For more information about using common controls, see the article Controls and Common Controls in the Windows SDK.

Example

// This code fragment is taken from CMainFrame::OnCreate
// CMainFrame is derived from CMDIFrameWnd.

//This example shows how to add text to toolbar buttons.
if (!m_wndToolBar.CreateEx(this, TBSTYLE_FLAT, WS_CHILD | WS_VISIBLE
   | CBRS_TOP) || !m_wndToolBar.LoadToolBar(IDR_MAINFRAME))
{
   TRACE0("Failed to create toolbar\n");
   return -1;      // fail to create
}

//Show text on toolbar buttons.
VERIFY(m_wndToolBar.SetButtonText(0, _T("New")));
VERIFY(m_wndToolBar.SetButtonText(1, _T("Open")));
VERIFY(m_wndToolBar.SetButtonText(2, _T("Save")));
VERIFY(m_wndToolBar.SetButtonText(4, _T("Cut")));
VERIFY(m_wndToolBar.SetButtonText(5, _T("Copy")));
VERIFY(m_wndToolBar.SetButtonText(6, _T("Paste")));
VERIFY(m_wndToolBar.SetButtonText(8, _T("Print")));
VERIFY(m_wndToolBar.SetButtonText(9, _T("About")));

CRect temp;
m_wndToolBar.GetItemRect(0, &temp);
m_wndToolBar.GetToolBarCtrl().SetButtonSize(CSize(temp.Width(),
   temp.Height()));

CToolBar::LoadBitmap

Call this member function to load the bitmap specified by lpszResourceName or nIDResource.

BOOL LoadBitmap(LPCTSTR lpszResourceName);
BOOL LoadBitmap(UINT nIDResource);

Parameters

lpszResourceName
Pointer to the resource name of the bitmap to be loaded.

nIDResource
Resource ID of the bitmap to be loaded.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The bitmap should contain one image for each toolbar button. If the images aren't of the standard size (16 pixels wide and 15 pixels high), call SetSizes to set the button sizes and their images.

CToolBar::LoadToolBar

Call this member function to load the toolbar specified by lpszResourceName or nIDResource.

BOOL LoadToolBar(LPCTSTR lpszResourceName);
BOOL LoadToolBar(UINT nIDResource);

Parameters

lpszResourceName
Pointer to the resource name of the toolbar to be loaded.

nIDResource
Resource ID of the toolbar to be loaded.

Return Value

Nonzero if successful; otherwise 0.

Remarks

See toolbar editor in for more information about creating a toolbar resource.

Example

See the example for CToolBar::CreateEx.

CToolBar::SetBitmap

Call this member function to set the bitmap image for the toolbar.

BOOL SetBitmap(HBITMAP hbmImageWell);

Parameters

hbmImageWell
Handle of a bitmap image that is associated with a toolbar.

Return Value

Nonzero if successful; otherwise 0.

Remarks

For example, call SetBitmap to change the bitmapped image after the user takes an action on a document that changes the action of a button.

CToolBar::SetButtonInfo

Call this member function to set the button's command ID, style, and image number.

void SetButtonInfo(
    int nIndex,
    UINT nID,
    UINT nStyle,
    int iImage);

Parameters

nIndex
Zero-based index of the button or separator for which information is to be set.

nID
The value to which the button's command ID is set.

nStyle
The new button style. The following button styles are supported:

• TBBS_BUTTON Standard pushbutton (default)

• TBBS_SEPARATOR Separator

• TBBS_CHECKBOX Auto check-box button

• TBBS_GROUP Marks the start of a group of buttons

• TBBS_CHECKGROUP Marks the start of a group of check-box buttons

• TBBS_DROPDOWN Creates a drop-down list button.

• TBBS_AUTOSIZE The button's width will be calculated based on the text of the button, not on the size of the image.

• TBBS_NOPREFIX The button text won't have an accelerator prefix associated with it.

iImage
New index for the button's image within the bitmap.

Remarks

For separators, which have the style TBBS_SEPARATOR, this function sets the separator's width in pixels to the value stored in iImage.

For information on bitmap images and buttons, see the CToolBar Overview and CToolBar::LoadBitmap.

CToolBar::SetButtons

This member function sets each toolbar button's command ID to the value specified by the corresponding element of the array lpIDArray.

BOOL SetButtons(
    const UINT* lpIDArray,
    int nIDCount);

Parameters

lpIDArray
Pointer to an array of command Ids. It can be NULL to allocate empty buttons.

nIDCount
Number of elements in the array pointed to by lpIDArray.

Return Value

Nonzero if successful; otherwise 0.

Remarks

If an element of the array has the value ID_SEPARATOR, a separator is created in the corresponding position of the toolbar. This function also sets each button's style to TBBS_BUTTON and each separator's style to TBBS_SEPARATOR, and assigns an image index to each button. The image index specifies the position of the button's image within the bitmap.

You don't need to account for separators in the bitmap because this function doesn't assign image indexes for separators. If your toolbar has buttons at positions 0, 1, and 3 and a separator at position 2, the images at positions 0, 1, and 2 in your bitmap are assigned to the buttons at positions 0, 1, and 3, respectively.

If lpIDArray is NULL, this function allocates space for the number of items specified by nIDCount. Use SetButtonInfo to set each item's attributes.

CToolBar::SetButtonStyle

Call this member function to set the style of a button or separator, or to group buttons.

void SetButtonStyle(
    int nIndex,
    UINT nStyle);

Parameters

nIndex
Index of the button or separator whose information is to be set.

nStyle
The button style. The following button styles are supported:

• TBBS_BUTTON Standard pushbutton (default)

• TBBS_SEPARATOR Separator

• TBBS_CHECKBOX Auto check-box button

• TBBS_GROUP Marks the start of a group of buttons

• TBBS_CHECKGROUP Marks the start of a group of check-box buttons

• TBBS_DROPDOWN Creates a drop-down list button

• TBBS_AUTOSIZE The button's width will be calculated based on the text of the button, not on the size of the image

• TBBS_NOPREFIX The button text won't have an accelerator prefix associated with it

Remarks

A button's style determines how the button appears and how it responds to user input.

Before calling SetButtonStyle, call the GetButtonStyle member function to retrieve the button or separator style.

CToolBar::SetButtonText

Call this function to set the text on a button.

BOOL SetButtonText(
    int nIndex,
    LPCTSTR lpszText);

Parameters

nIndex
Index of the button whose text is to be set.

lpszText
Points to the text to be set on a button.

Return Value

Nonzero if successful; otherwise 0.

Example

See the example for CToolBar::GetToolBarCtrl.

CToolBar::SetHeight

This member function sets the toolbar's height to the value, in pixels, specified in cyHeight.

void SetHeight(int cyHeight);

Parameters

cyHeight
The height in pixels of the toolbar.

Remarks

After calling SetSizes, use this member function to override the standard toolbar height. If the height is too small, the buttons will be clipped at the bottom.

If this function isn't called, the framework uses the size of the button to determine the toolbar height.

CToolBar::SetSizes

Call this member function to set the toolbar's buttons to the size, in pixels, specified in sizeButton.

void SetSizes(
    SIZE sizeButton,
    SIZE sizeImage);

Parameters

sizeButton
The size in pixels of each button.

sizeImage
The size in pixels of each image.

Remarks

The sizeImage parameter must contain the size, in pixels, of the images in the toolbar's bitmap. The dimensions in sizeButton must be sufficient to hold the image plus 7 pixels extra in width and 6 pixels extra in height. This function also sets the toolbar height to fit the buttons.

Call this member function only for toolbars that don't follow Windows Interface Guidelines for Software Design recommendations for button and image sizes.

Example

// This code fragment is taken from CMainFrame::OnCreate
// CMainFrame is derived from CMDIFrameWnd

// This example shows how to add text to toolbar buttons.
if (!m_wndToolBar.CreateEx(this, TBSTYLE_FLAT, WS_CHILD | WS_VISIBLE 
   | CBRS_TOP) || !m_wndToolBar.LoadToolBar(IDR_MAINFRAME))
{
   TRACE0("Failed to create toolbar\n");
   return -1;      // fail to create
}

//Show text on toolbar buttons.
VERIFY(m_wndToolBar.SetButtonText(0, _T("New")));
VERIFY(m_wndToolBar.SetButtonText(1, _T("Open")));
VERIFY(m_wndToolBar.SetButtonText(2, _T("Save")));
VERIFY(m_wndToolBar.SetButtonText(4, _T("Cut")));
VERIFY(m_wndToolBar.SetButtonText(5, _T("Copy")));
VERIFY(m_wndToolBar.SetButtonText(6, _T("Paste")));
VERIFY(m_wndToolBar.SetButtonText(8, _T("Print")));
VERIFY(m_wndToolBar.SetButtonText(9, _T("About")));

CRect temp;
m_wndToolBar.GetItemRect(0,&temp);
m_wndToolBar.SetSizes(CSize(temp.Width(),
   temp.Height()),CSize(16,15));

See also

MFC Sample CTRLBARS
MFC Sample DLGCBR32
MFC Sample DOCKTOOL
CControlBar Class
Hierarchy Chart
CToolBarCtrl Class