`CMFCToolBar` Class

Article
06/14/2022

The CMFCToolBar class resembles CToolBar Class, but provides additional support for user interface features. These include flat toolbars, toolbars with hot images, large icons, pager buttons, locked toolbars, rebar controls, text under images, background images, and tabbed toolbars. The CMFCToolBar class also contains built-in support for user customization of toolbars and menus, drag-and-drop between toolbars and menus, combo box buttons, edit box buttons, color pickers, and roll-up buttons.

For more detail, see the source code located in your Visual Studio installation, for example, %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc.

Syntax

class CMFCToolBar : public CMFCBaseToolBar

Members

Public Constructors

Name	Description
`CMFCToolBar::CMFCToolBar`	Default constructor.
`CMFCToolBar::~CMFCToolBar`	Destructor.

Public Methods

Name	Description
`CMFCToolBar::AddBasicCommand`	Adds a menu command to the list of commands that are always displayed when a user opens a menu.
`CMFCToolBar::AddCommandUsage`	Increments by one the counter that is associated with the given command.
`CMFCToolBar::AddToolBarForImageCollection`	Adds images from the user interface resources to the collection of images in the application.
`CMFCToolBar::AdjustLayout`	Recalculates the size and position of a toolbar. (Overrides `CBasePane::AdjustLayout`).
`CMFCToolBar::AdjustSize`	Recalculates the size of the toolbar.
`CMFCToolBar::AllowChangeTextLabels`	Specifies whether text labels can be shown under images on the toolbar buttons.
`CMFCToolBar::AreTextLabels`	Specifies whether text labels under images are currently displayed on the toolbar buttons.
`CMFCToolBar::AutoGrayInactiveImages`	Enable or disables the automatic generation of inactive button images.
`CMFCToolBar::ButtonToIndex`	Returns the index of a specified `CMFCToolBarButton` Class object in this toolbar.
`CMFCToolBar::CalcFixedLayout`	Calculates the horizontal size of the toolbar. (Overrides `CBasePane::CalcFixedLayout`.)
`CMFCToolBar::CalcSize`	Called by the framework as part of the layout calculation process. (Overrides `CPane::CalcSize`.)
`CMFCToolBar::CanHandleSiblings`	Determines whether the toolbar and its sibling are positioned on the same pane.
`CMFCToolBar::CleanUpImages`	Frees the system resources allocated for toolbar images.
`CMFCToolBar::CleanUpLockedImages`	Frees the system resources allocated for locked toolbar images.
`CMFCToolBar::CanBeClosed`	Specifies whether a user can close the toolbar. (Overrides `CBasePane::CanBeClosed`.)
`CMFCToolBar::CanBeRestored`	Determines whether the system can restore a toolbar to its original state after customization.
`CMFCToolBar::CanFocus`	Specifies whether the pane can receive focus. (Overrides `CBasePane::CanFocus`.)
`CMFCToolBar::CanHandleSiblings`	Determines whether the toolbar and its sibling are positioned on the same pane.
`CMFCToolBar::CommandToIndex`	Returns the index of the button in the toolbar with a specified command ID.
`CMFCToolBar::Create`	Creates a `CMFCToolBar` object.
`CMFCToolBar::CreateEx`	Creates a `CMFCToolBar` object that uses additional style options, such as large icons.
`CMFCToolBar::Deactivate`	Deactivates the toolbar.
`CMFCToolBar::EnableCustomizeButton`	Enables or disables the Add or Remove Buttons button that appears on the end of the toolbar.
`CMFCToolBar::EnableDocking`	Enables docking of the pane to the main frame. (Overrides `CBasePane::EnableDocking`.)
`CMFCToolBar::EnableLargeIcons`	Enables or disables large icons on toolbar buttons.
`CMFCToolBar::EnableQuickCustomization`	Enables or disables the quick customization of toolbars so that the user can press the Alt key and drag a button to a new location.
`CMFCToolBar::EnableReflections`	Enables or disables command reflection.
`CMFCToolBar::EnableTextLabels`	Enables or disables text labels under toolbar button images.
`CMFCToolBar::FromHandlePermanent`	Retrieves a pointer to the `CMFCToolBar` object that contains the given window handle.
`CMFCToolBar::GetAllButtons`	Returns a read-only list of buttons in a toolbar.
`CMFCToolBar::GetAllToolbars`	Returns a read-only list of all toolbars in the application.
`CMFCToolBar::GetBasicCommands`	Returns a read-only list of the basic commands defined in the application.
`CMFCToolBar::GetButton`	Returns a pointer to the `CMFCToolBarButton` object that has a specified toolbar button index.
`CMFCToolBar::GetButtonInfo`	Returns the command ID, style, and image index of the button at a specified index.
`CMFCToolBar::GetButtonSize`	Returns the dimensions of each button on the toolbar.
`CMFCToolBar::GetButtonStyle`	Returns the current style of the toolbar button that is located at the specified index.
`CMFCToolBar::GetButtonText`	Returns the text label of a button that has a specified index.
`CMFCToolBar::GetColdImages`	Returns a pointer to the collection of cold toolbar button images in the application.
`CMFCToolBar::GetColumnWidth`	Returns the width of the toolbar buttons.
`CMFCToolBar::GetCommandButtons`	Returns a list of buttons that have a specified command ID from all toolbars in the application.
`CMFCToolBar::GetCount`	Returns the number of buttons and separators on the toolbar.
`CMFCToolBar::GetCustomizeButton`	Retrieves a pointer to the `CMFCCustomizeButton` object that is associated with the toolbar.
`CMFCToolBar::GetDefaultImage`	Returns the index of the default image for a toolbar button with a specified command ID.
`CMFCToolBar::GetDisabledImages`	Returns a pointer to the collection of images that are used for disabled toolbar buttons in the application.
`CMFCToolBar::GetDisabledMenuImages`	Returns a pointer to the collection of images that are used for disabled menu buttons in the application.
`CMFCToolBar::GetDroppedDownMenu`	Retrieves a pointer to the menu button object that is currently displaying its sub-menu.
`CMFCToolBar::GetGrayDisabledButtons`	Specifies whether the images of disabled buttons are dimmed versions of the regular button images, or taken from the collection of disabled button images.
`CMFCToolBar::GetHighlightedButton`	Returns a pointer to the toolbar button that is currently highlighted.
`CMFCToolBar::GetHotBorder`	Determines whether the toolbar buttons are hot-tracked.
`CMFCToolBar::GetHotTextColor`	Returns the text color of the highlighted toolbar buttons.
`CMFCToolBar::GetHwndLastFocus`	Returns a handle to the window that had the input focus just before the toolbar did.
`CMFCToolBar::GetIgnoreSetText`	Specifies whether calls to set button labels are ignored.
`CMFCToolBar::GetImageSize`	Returns the current size of toolbar button images.
`CMFCToolBar::GetImages`	Returns a pointer to the collection of default button images in the application.
`CMFCToolBar::GetImagesOffset`	Returns the index offset used to find the toolbar button images for this toolbar in the global list of toolbar button images.
`CMFCToolBar::GetInvalidateItemRect`	Retrieves the region of the client area that must be redrawn for the button at the given index.
`CMFCToolBar::GetItemID`	Returns the command ID of the toolbar button at a specified index.
`CMFCToolBar::GetItemRect`	Returns the bounding rectangle of the button at a specified index.
`CMFCToolBar::GetLargeColdImages`	Returns a pointer to the collection of large cold toolbar button images in the application.
`CMFCToolBar::GetLargeDisabledImages`	Returns a pointer to the collection of large disabled toolbar button images in the application.
`CMFCToolBar::GetLargeImages`	Returns a pointer to the collection of large toolbar button images in the application.
`CMFCToolBar::GetLockedColdImages`	Returns a pointer to the collection of locked cold images in the toolbar.
`CMFCToolBar::GetLockedDisabledImages`	Returns a pointer to the collection of locked disabled images in the toolbar.
`CMFCToolBar::GetLockedImages`	Returns a pointer to the collection of locked button images in the toolbar.
`CMFCToolBar::GetLockedImageSize`	Returns the default size of locked toolbar images.
`CMFCToolBar::GetLockedMenuImages`	Returns a pointer to the collection of locked toolbar menu images in the toolbar.
`CMFCToolBar::GetMenuButtonSize`	Returns the size of menu buttons in the application.
`CMFCToolBar::GetMenuImageSize`	Returns the size of menu button images in the application.
`CMFCToolBar::GetMenuImages`	Returns a pointer to the collection of menu button images in the application.
`CMFCToolBar::GetOrigButtons`	Retrieves the collection of non-customized buttons of the toolbar.
`CMFCToolBar::GetOrigResetButtons`	Retrieves the collection of non-customized reset buttons of the toolbar.
`CMFCToolBar::GetResourceID`	Retrieves the resource ID of the toolbar.
`CMFCToolBar::GetRouteCommandsViaFrame`	Determines which object, the parent frame or the owner, sends commands to the toolbar.
`CMFCToolBar::GetRowHeight`	Returns the height of toolbar buttons.
`CMFCToolBar::GetShowTooltips`	Specifies whether tool tips are displayed for toolbar buttons.
`CMFCToolBar::GetSiblingToolBar`	Retrieves the sibling of the toolbar.
`CMFCToolBar::GetUserImages`	Returns a pointer to the collection of user-defined toolbar button images in the application.
`CMFCToolBar::HitTest`	Returns the index of the toolbar button that is located at the specified position.
`CMFCToolBar::InsertButton`	Inserts a button into the toolbar.
`CMFCToolBar::InsertSeparator`	Inserts a separator into the toolbar.
`CMFCToolBar::InvalidateButton`	Invalidates the client area of the toolbar button that exists at the provided index.
`CMFCToolBar::IsAddRemoveQuickCustomize`	Determines whether a user can add or remove toolbar buttons by using the Customize menu option.
`CMFCToolBar::IsAltCustomizeMode`	Specifies whether quick customization is being used to drag a button.
`CMFCToolBar::IsAutoGrayInactiveImages`	Specifies whether the automatic generation of inactive (non-highlighted) button images is enabled.
`CMFCToolBar::IsBasicCommand`	Determines whether a command is on the list of basic commands.
`CMFCToolBar::IsButtonExtraSizeAvailable`	Determines whether the toolbar can display buttons that have extended borders.
`CMFCToolBar::IsButtonHighlighted`	Determines whether a button on the toolbar is highlighted.
`CMFCToolBar::IsCommandPermitted`	Determines whether a command is permitted.
`CMFCToolBar::IsCommandRarelyUsed`	Determines whether a command is rarely used (see `CMFCToolBar::SetCommandUsageOptions`).
`CMFCToolBar::IsCustomizeMode`	Specifies whether the toolbar framework is in customization mode.
`CMFCToolBar::IsDragButton`	Determines whether a toolbar button is being dragged.
`CMFCToolBar::IsExistCustomizeButton`	Determines whether the toolbar contains the Customize button.
`CMFCToolBar::IsFloating`	Determines whether the toolbar is floating.
`CMFCToolBar::IsLargeIcons`	Specifies whether toolbars in the application currently display large icons.
`CMFCToolBar::IsLastCommandFromButton`	Determines whether the most recently executed command was sent from the specified toolbar button.
`CMFCToolBar::IsLocked`	Determines whether the toolbar is locked.
`CMFCToolBar::IsOneRowWithSibling`	Determines whether the toolbar and its sibling toolbar are positioned on the same row.
`CMFCToolBar::IsUserDefined`	Specifies whether the toolbar is user-defined.
`CMFCToolBar::LoadBitmap`	Loads toolbar images from application resources.
`CMFCToolBar::LoadBitmapEx`	Loads toolbar images from application resources. Includes large images.
`CMFCToolBar::LoadParameters`	Loads global toolbar options from the Windows registry.
`CMFCToolBar::LoadState`	Loads the toolbar state information from the Windows registry. (Overrides `CPane::LoadState`.)
`CMFCToolBar::LoadToolBar`	Loads the toolbar from application resources.
`CMFCToolBar::LoadToolBarEx`	Loads the toolbar from application resources by using the `CMFCToolBarInfo` helper class to enable the application to use large images.
`CMFCToolBar::OnChangeHot`	Called by the framework when a user selects a button on the toolbar.
`CMFCToolBar::OnFillBackground`	Called by the framework from `CBasePane::DoPaint` to fill the toolbar background.
`CMFCToolBar::OnReset`	Restores the toolbar to its original state.
`CMFCToolBar::OnSetAccData`	(Overrides `CBasePane::OnSetAccData`.)
`CMFCToolBar::OnSetDefaultButtonText`	Restores the text of a toolbar button to its default state.
`CMFCToolBar::OnUpdateCmdUI`	Used internally.
`CMFCToolBar::RemoveAllButtons`	Removes all buttons from the toolbar.
`CMFCToolBar::RemoveButton`	Removes the button with the specified index from the toolbar.
`CMFCToolBar::RemoveStateFromRegistry`	Deletes the state information for the toolbar from the Windows registry.
`CMFCToolBar::ReplaceButton`	Replaces a toolbar button with another toolbar button.
`CMFCToolBar::ResetAll`	Restores all toolbars to their original states.
`CMFCToolBar::ResetAllImages`	Clears all toolbar image collections in the application.
`CMFCToolBar::RestoreOriginalState`	Restores the original state of a toolbar.
`CMFCToolBar::SaveState`	Saves the state information for the toolbar in the Windows registry. (Overrides `CPane::SaveState`.)
`CMFCToolBar::Serialize`	(Overrides `CBasePane::Serialize`.)
`CMFCToolBar::SetBasicCommands`	Sets the list of commands that are always displayed when a user opens a menu.
`CMFCToolBar::SetButtonInfo`	Sets the command ID, style, and image ID of a toolbar button.
`CMFCToolBar::SetButtonStyle`	Sets the style of the toolbar button at the given index.
`CMFCToolBar::SetButtonText`	Sets the text label of a toolbar button.
`CMFCToolBar::SetButtons`	Sets the buttons for the toolbar.
`CMFCToolBar::SetCommandUsageOptions`	Specifies when rarely used commands do not appear in the menu of the application.
`CMFCToolBar::SetCustomizeMode`	Enables or disables customization mode for all toolbars in the application.
`CMFCToolBar::SetGrayDisabledButtons`	Specifies whether the disabled buttons on the toolbar are dimmed or if disabled images are used for the disabled buttons.
`CMFCToolBar::SetHeight`	Sets the height of the toolbar.
`CMFCToolBar::SetHotBorder`	Specifies whether toolbar buttons are hot-tracked.
`CMFCToolBar::SetHotTextColor`	Sets the text color for hot toolbar buttons.
`CMFCToolBar::SetLargeIcons`	Specifies whether toolbar buttons display large icons.
`CMFCToolBar::SetLockedSizes`	Sets the sizes of locked buttons and locked images on the toolbar.
`CMFCToolBar::SetMenuSizes`	Sets the size of toolbar menu buttons and their images.
`CMFCToolBar::SetNonPermittedCommands`	Sets the list of commands that cannot be executed by the user.
`CMFCToolBar::SetOneRowWithSibling`	Positions the toolbar and its sibling on the same row.
`CMFCToolBar::SetPermament`	Specifies whether a user can close the toolbar.
`CMFCToolBar::SetRouteCommandsViaFrame`	Specifies whether the parent frame or the owner sends commands to the toolbar.
`CMFCToolBar::SetShowTooltips`	Specifies whether the framework displays tool tips.
`CMFCToolBar::SetSiblingToolBar`	Specifies the sibling of the toolbar.
`CMFCToolBar::SetSizes`	Specifies the sizes of buttons and images on all toolbars.
`CMFCToolBar::SetToolBarBtnText`	Specifies properties of a button on the toolbar.
`CMFCToolBar::SetTwoRowsWithSibling`	Positions the toolbar and its sibling on separate rows.
`CMFCToolBar::SetUserImages`	Sets the collection of user-defined images in the application.
`CMFCToolBar::StretchPane`	Stretches the toolbar vertically or horizontally. (Overrides `CBasePane::StretchPane`.)
`CMFCToolBar::TranslateChar`	Executes a button command if the specified key code corresponds to a valid keyboard shortcut.
`CMFCToolBar::UpdateButton`	Updates the state of the specified button.
`CMFCToolBar::WrapToolBar`	Repositions toolbar buttons within the given dimensions.

Protected Methods

Name	Description
`CMFCToolBar::AllowShowOnList`	Determines whether the toolbar is displayed in the list on the Toolbars pane of the Customize dialog box.
`CMFCToolBar::CalcMaxButtonHeight`	Calculates the maximum height of a button in the toolbar.
`CMFCToolBar::DoPaint`	Repaints a toolbar.
`CMFCToolBar::DrawButton`	Repaints a toolbar button.
`CMFCToolBar::DrawSeparator`	Repaints a separator on a toolbar.
`CMFCToolBar::OnUserToolTip`	Called by the framework when the tooltip for a button is about to be displayed.

Data Members

Name	Description
`CMFCToolBar::m_bDontScaleImages`	Specifies whether to scale or not toolbar images in high DPI mode.
`CMFCToolBar::m_dblLargeImageRatio`	Specifies the ratio between the dimension (height or width) of large images and the dimension of regular images.

Remarks

To incorporate a CMFCToolBar object into your application, follow these steps:

Add a CMFCToolBar object to the main frame window.
When you process the WM_CREATE message for the main frame window, call either CMFCToolBar::Create or CMFCToolBar::CreateEx to create the toolbar and specify its style.
Call CBasePane::EnableDocking to specify the docking style.

To insert a special button, such as a combo box or drop-down toolbar, reserve a dummy button in the parent resource, and replace the dummy button at runtime by using CMFCToolBar::ReplaceButton. For more information, see Walkthrough: Putting Controls On Toolbars.

CMFCToolBar is the base class for the MFC Library classes CMFCMenuBar Class, CMFCPopupMenuBar Class, and CMFCDropDownToolBar Class.

Example

The following example demonstrates how to use various methods in the CMFCToolBar class. The example shows how to set the text of the window label of the tool bar, set the borders, set the style of the pane, and enable the Add or Remove Buttons button that appears on the end of the toolbar. This code snippet is part of the IE Demo sample.

CMFCToolBar m_wndToolBar;

m_wndToolBar.SetWindowText(_T("Standard"));
m_wndToolBar.SetBorders();

//------------------------------------
// Remove toolbar gripper and borders:
//------------------------------------
m_wndToolBar.SetPaneStyle(m_wndToolBar.GetPaneStyle() &
                          ~(CBRS_GRIPPER | CBRS_BORDER_TOP | CBRS_BORDER_BOTTOM | CBRS_BORDER_LEFT | CBRS_BORDER_RIGHT));

m_wndToolBar.EnableCustomizeButton(TRUE, ID_VIEW_CUSTOMIZE, _T("Customize..."));

Requirements

Header: afxtoolbar.h

Inheritance Hierarchy

CMFCToolBar

`CMFCToolBar::AddBasicCommand`

Adds a menu command to the list of commands that are always displayed when a user opens a menu.

static void __stdcall AddBasicCommand(UINT uiCmd);

Parameters

uiCmd
[in] Specifies the command to add.

Remarks

A basic command is always displayed when the menu is opened. This method is meaningful when the user chooses to view recently used commands.

Use the CMFCToolBar::SetBasicCommands method to set the list of commands that are always displayed when a user opens a menu. Use the CMFCToolBar::GetBasicCommands method to retrieve the list of basic commands that is used by your application.

`CMFCToolBar::AddCommandUsage`

Increments by one the counter that is associated with the given command.

static void __stdcall AddCommandUsage(UINT uiCommand);

Parameters

uiCommand
[in] Specifies the command counter to increment.

Remarks

The framework calls this method when the user selects a menu item.

The framework uses command counters to display recently used menu items.

This method increments the command counter by using the CMFCCmdUsageCount::AddCmd method.

`CMFCToolBar::AddToolBarForImageCollection`

Adds images from the user interface resources to the collection of images in the application.

static BOOL __stdcall AddToolBarForImageCollection(
    UINT uiResID,
    UINT uiBmpResID=0,
    UINT uiColdResID=0,
    UINT uiMenuResID=0,
    UINT uiDisabledResID=0,
    UINT uiMenuDisabledResID=0);

Parameters

uiResID
[in] Resource ID of a toolbar with images to load.

uiBmpResID
[in] Resource ID of a bitmap with toolbar images.

uiColdResID
[in] Resource ID of a bitmap with "cold" toolbar images.

uiMenuResID
[in] Resource ID of a bitmap with menu images.

uiDisabledResID
[in] Resource ID of a bitmap with disabled toolbar images.

uiMenuDisabledResID
[in] Resource ID of a bitmap with disabled menu images.

Return Value

TRUE if the method succeeds; FALSE if uiResID or uiBmpResID do not specify valid resources, or another error occurs.

Remarks

Call this method to load a bitmap with toolbar images and add it to the collection of toolbar images. This method creates a temporary toolbar object and calls CMFCToolBar::LoadToolBar.

`CMFCToolBar::AdjustLayout`

Recalculates the size and position of a toolbar.

virtual void AdjustLayout();

Remarks

Call this method when the toolbar has been created to recalculate its size and position.

The framework calls this method every time that the layout of the toolbar must be changed. For example, the layout must change when the user moves another control bar, resizes an application window, or customizes the toolbar.

Override this method to provide your own dynamic layout in classes that you derive from CMFCToolbar.

`CMFCToolBar::AdjustSize`

Recalculates the size of the toolbar.

void AdjustSize();

Remarks

This method makes sure that the toolbar fits in the bounds of the parent frame. This method does nothing if the toolbar has no parent frame.

The CMFCToolBar::AdjustLayout method calls this method to recalculate the size if the parent of the toolbar is not a CMFCReBar object.

`CMFCToolBar::AllowChangeTextLabels`

Specifies whether text labels can be shown under images on the toolbar buttons.

virtual BOOL AllowChangeTextLabels() const;

Return Value

TRUE if it is allowed to display text labels below images; otherwise FALSE.

Remarks

This method is called by the customization dialog box to determine whether to enable a Show text labels check-box on the Toolbars page for the selected toolbar.

The default implementation returns TRUE.

Override this method in an object derived from CMFCToolBar and return FALSE when you do not want the user to decide whether text labels are displayed on toolbar buttons under the images.

`CMFCToolBar::AllowShowOnList`

Determines whether the toolbar is displayed in the list of toolbars on the Toolbars pane of the Customize dialog box.

virtual BOOL AllowShowOnList() const;

Return Value

TRUE if the toolbar object can be displayed in the list box on the toolbar customization page; otherwise FALSE.

Remarks

This method is called by the framework to determine whether the list on the toolbar customization page should include a particular object derived from CMFCToolBar.

The default implementation always returns TRUE. Override this method when you do not want a toolbar to appear in the toolbars list in the customization dialog box.

`CMFCToolBar::AreTextLabels`

Specifies whether text labels under images are currently displayed on the toolbar buttons.

BOOL AreTextLabels() const;

Return Value

TRUE if the toolbar buttons display text labels below images; otherwise FALSE.

Remarks

Use CMFCToolBar::EnableTextLabels to specify whether the text is displayed. The default value is FALSE. Call CMFCToolBar::AllowChangeTextLabels to specify whether the user can change this setting in the customization dialog box.

`CMFCToolBar::AutoGrayInactiveImages`

Enable or disables the automatic generation of inactive button images.

static void AutoGrayInactiveImages(
    BOOL bEnable=TRUE,
    int nGrayImagePercentage=0,
    BOOL bRedrawAllToolbars=TRUE);

Parameters

bEnable
[in] A Boolean value that specifies whether to dim inactive images. If this parameter is TRUE, inactive images are dimmed. Otherwise, inactive images are not dimmed.

nGrayImagePercentage
[in] Specifies the luminance percentage for inactive images. If bEnable is FALSE, this value is ignored.

bRedrawAllToolbars
[in] A Boolean value that specifies whether to redraw all toolbars in the application. If this parameter is TRUE, this method redraws all toolbars.

Remarks

If bEnable is TRUE, the framework uses nGrayImagePercentage to generate inactive images from the regular images. Otherwise, you must provide the set of inactive images by using the CMFCToolBar::GetColdImages method. By default, this option is disabled.

For more information about the nGrayImagePercentage parameter, see CMFCToolBarImages::GrayImages.

`CMFCToolBar::ButtonToIndex`

Returns the index of a specified CMFCToolBarButton Class object in this toolbar.

int ButtonToIndex(const CMFCToolBarButton* pButton) const;

Parameters

pButton
[in] A pointer to the toolbar button object.

Return Value

Index of pButton in the internal list of toolbar buttons; or -1 if the specified button is not on this toolbar.

`CMFCToolBar::CalcFixedLayout`

Calculates the horizontal size of the toolbar.

virtual CSize CalcFixedLayout(
    BOOL bStretch,
    BOOL bHorz);

Parameters

bStretch
[in] TRUE to stretch the toolbar to the size of the parent frame.

bHorz
[in] TRUE to orient the toolbar horizontally; FALSE to orient the toolbar vertically.

Return Value

A CSize object that specifies the size of the toolbar.

Remarks

This method calculates the size of the toolbar by using the CMFCToolBar::CalcLayout method. It passes the LM_STRETCH flag for the dwMode parameter if bStretch is TRUE. It passes the LM_HORZ flag if bHorz is TRUE.

See the VisualStudioDemo sample for an example that uses this method.

`CMFCToolBar::CalcMaxButtonHeight`

Calculates the maximum height of buttons in the toolbar.

virtual int CalcMaxButtonHeight();

Return Value

The maximum height of buttons.

Remarks

This method calculates the maximum height among all toolbar buttons on the toolbar. The height may vary depending on factors such as the current toolbar docking state.

Override this method in a class derived from CMFCToolBar to provide your own height calculation.

`CMFCToolBar::CalcSize`

Called by the framework as part of the layout calculation process.

virtual CSize CalcSize(BOOL bVertDock);

Parameters

bVertDock
[in] TRUE to specify that the toolbar is docked vertically; FALSE to specify that the toolbar is docked horizontally.

Return Value

A CSize object that specifies the overall size of the buttons on the toolbar.

Remarks

This method considers the attributes that affect the size of each button, such as the area of the text label and the border size.

If the toolbar contains no buttons, this method returns the reserved size of a single button by using the CMFCToolBar::GetButtonSize method.

`CMFCToolBar::CanBeClosed`

Specifies whether a user can close the toolbar.

virtual BOOL CanBeClosed() const;

Return Value

TRUE if the toolbar can be closed by the user; otherwise FALSE.

Remarks

The framework calls this method to determine whether the user can close a toolbar. If the method returns TRUE, the framework enables the SC_CLOSE command in the system menu of the toolbar and the user can close the toolbar by using a check box in the list of toolbars in the customization dialog box.

The default implementation returns TRUE. Override this method in a class derived from CMFCToolBar to make toolbar objects that cannot be closed by the user.

`CMFCToolBar::CanBeRestored`

Determines whether the system can restore a toolbar to its original state after customization.

virtual BOOL CanBeRestored() const;

Return Value

TRUE if the toolbar can be restored from the application resources; otherwise FALSE.

Remarks

The framework calls this method to determine whether a toolbar can be returned to its original state after customization. The original state is loaded from the application resources.

If CanBeRestored returns TRUE, the Toolbars page of the customization dialog box enables the Reset button for the selected toolbar.

The default implementation returns TRUE if the original resource ID of the toolbar when it was loaded is non-zero. Usually, only user-defined toolbars cannot be restored.

You can override the CanBeRestored method to customize this behavior in derived classes.

`CMFCToolBar::CanFocus`

Specifies whether the pane can receive focus.

virtual BOOL CanFocus() const;

Return Value

This method returns FALSE.

Remarks

This method overrides the base class implementation, CBasePane::CanFocus, because toolbar objects cannot receive focus.

`CMFCToolBar::CanHandleSiblings`

Determines whether the toolbar and its sibling are positioned on the same pane.

BOOL CanHandleSiblings();

Return Value

TRUE if the toolbar has a sibling and the toolbar and its sibling are positioned on the same pane; otherwise FALSE.

Remarks

The internal CMFCCustomizeButton::CreatePopupMenu method calls this method to determine how to show the Customize pop-up menu. If this method returns TRUE, the framework displays the Show Buttons on One Row or Show Buttons on Two Rows buttons.

You typically do not have to use this method. To enable the Customize button that appears on the toolbar, call the CMFCToolBar::EnableCustomizeButton method. To enable the Show Buttons on One Row or Show Buttons on Two Rows buttons, call CMFCToolBar::SetSiblingToolBar.

`CMFCToolBar::CleanUpImages`

Frees the system resources allocated for toolbar images.

static void CMFCToolBar::CleanUpImages();

Remarks

The framework calls this method when an application shuts down.

`CMFCToolBar::CleanUpLockedImages`

Frees the system resources allocated for locked toolbar images.

void CleanUpLockedImages();

Remarks

Call this method when the visual style of your application changes. See the VisualStudioDemo sample for an example that uses this method.

`CMFCToolBar::CommandToIndex`

Returns the index of the button in the toolbar with a specified command ID.

int CommandToIndex(
    UINT nIDFind,
    int iIndexFirst=0) const;

Parameters

nIDFind
[in] Specifies the command ID.

iIndexFirst
[in] Specifies the initial index to start from.

Return Value

Zero-based index of the toolbar button if the method was successful; -1 if there is no button with the specified ID.

Remarks

A CMFCToolBar object maintains an internal list of the buttons on the toolbar. Call this function to retrieve the index of a button in the list given the command ID of the button.

If iIndex is greater than 0, this method ignores any button on the toolbar that has an index less than iIndex.

`CMFCToolBar::Create`

Creates a CMFCToolBar object.

virtual BOOL Create(
    CWnd* pParentWnd,
    DWORD dwStyle=AFX_DEFAULT_TOOLBAR_STYLE,
    UINT nID=AFX_IDW_TOOLBAR);

Parameters

pParentWnd
[in] A pointer to the parent window of the toolbar.

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

nID
[in] The ID of the child window of the toolbar.

Return Value

TRUE if this method succeeds; otherwise FALSE.

Remarks

This method creates a control bar and attaches it to the toolbar. It creates the control bar with the TBSTYLE_FLAT style. Call CMFCToolBar::CreateEx if you want a different control bar style.

`CMFCToolBar::CreateEx`

Creates a CMFCToolBar object that uses additional style options, such as large icons.

virtual BOOL CreateEx(
    CWnd* pParentWnd,
    DWORD dwCtrlStyle=TBSTYLE_FLAT,
    DWORD dwStyle=AFX_DEFAULT_TOOLBAR_STYLE,
    CRect rcBorders=CRect(1,
    1,
    1,
    1),
    UINT nID=AFX_IDW_TOOLBAR);

Parameters

pParentWnd
[in] A pointer to the parent window of the toolbar.

dwCtrlStyle
[in] Additional styles for creating the embedded control bar object.

dwStyle
[in] The toolbar style. See Toolbar Control and Button Styles for a list of appropriate styles.

rcBorders
[in] A CRect object that specifies the widths of the toolbar window borders.

nID
[in] The ID of the child window of the toolbar.

Return Value

Nonzero if this method succeeds; otherwise 0.

Remarks

This method creates a control bar and attaches it to the toolbar.

Call this method instead of CMFCToolBar::Create when you want to provide specific styles. For example, set dwCtrlStyle to TBSTYLE_FLAT | TBSTYLE_TRANSPARENT to create a toolbar that resembles the toolbars that are used by Internet Explorer 4.

Example

The following example demonstrates how to use the CreateEx method of the CMFCToolBar class. This code snippet is part of the IE Demo sample.

CMFCToolBar m_wndToolBar;

// The this pointer points to CMainFrame class which extends the CFrameWnd class.
if (!m_wndToolBar.CreateEx(this, TBSTYLE_TRANSPARENT) ||
    !m_wndToolBar.LoadToolBar(IDR_MAINFRAME, uiToolbarColdID, uiMenuID,
                              FALSE /* Not locked */, 0, 0, uiToolbarHotID))
{
   TRACE0("Failed to create toolbar\n");
   return -1; // fail to create
}

`CMFCToolBar::Deactivate`

Deactivates the toolbar.

virtual void Deactivate();

Remarks

This method deactivates the toolbar by removing the focus from the highlighted toolbar button. The framework calls this method when the toolbar loses focus or is destroyed.

`CMFCToolBar::DoPaint`

Repaints a toolbar.

virtual void DoPaint(CDC* pDC);

Parameters

pDC
[in] A pointer to a device context.

Remarks

This method is called by the framework when a part of the toolbar must be repainted.

Override this method to customize the appearance of an object derived from CMFCToolBar.

`CMFCToolBar::DrawButton`

Repaints a toolbar button.

virtual BOOL DrawButton(
    CDC* pDC,
    CMFCToolBarButton* pButton,
    CMFCToolBarImages* pImages,
    BOOL bHighlighted,
    BOOL bDrawDisabledImages);

Parameters

pDC
[in] A pointer to a device context.

pButton
[in] A pointer to a button to draw.

pImages
[in] A pointer to the toolbar images.

bHighlighted
[in] TRUE if the button is highlighted; otherwise FALSE.

bDrawDisabledImages
[in] TRUE if disabled buttons are dimmed; otherwise FALSE.

Return Value

TRUE if the button was repainted; FALSE if the button is hidden.

Remarks

The CMFCToolBar::DrawButton method calls this method when a toolbar button must be repainted.

Override this method if you want to customize the appearance of buttons on your toolbar.

`CMFCToolBar::DrawSeparator`

Repaints a separator on a toolbar.

virtual void DrawSeparator(
    CDC* pDC,
    const CRect& rect,
    BOOL bHorz);

Parameters

pDC
[in] A pointer to a device context.

rect
[in] The bounding rectangle of the location where the separator is drawn, in pixels.

bHorz
[in] TRUE if the separator is horizontal, FALSE if the separator is vertical.

Remarks

CMFCToolBar::DoPaint calls this method for each CMFCToolBar::DrawSeparator object that has the TBBS_SEPARATOR style, instead of calling CMFCToolBar::DrawButton for those buttons.

Override this method in a class derived from CMFCToolBar to customize the appearance of separators on the toolbar. The default implementation calls CMFCVisualManager::OnDrawSeparator to draw a separator whose appearance is determined by the current visual manager.

`CMFCToolBar::EnableCustomizeButton`

Enables or disables the Customize button that appears on the toolbar.

void EnableCustomizeButton(
    BOOL bEnable,
    int iCustomizeCmd,
    const CString& strCustomizeText,
    BOOL bQuickCustomize=TRUE);

void EnableCustomizeButton(
    BOOL bEnable,
    int iCustomizeCmd,
    UINT uiCustomizeTextResId,
    BOOL bQuickCustomize=TRUE);

Parameters

bEnable
[in] Enables or disables the Customize button.

iCustomizeCmd
[in] The command ID of the Customize button.

strCustomizeText
[in] The text label of the Customize button.

uiCustomizeTextResId
[in] The resource string ID of the Customize button label.

bQuickCustomize
[in] Enables or disables the Add or Remove Buttons option on the menu that drops down from the button.

Remarks

If iCustomizeCmd is -1, the framework displays the Customize button when multiple toolbar buttons do not fit in the toolbar area. The button displays a double left-pointing arrow, or chevron, which indicates that there are more buttons.

If iCustomizeCmd specifies a valid command ID, and bEnable is TRUE, the Customize button is always displayed. The button has a small down arrow and opens a menu that contains a command. This command uses the text label specified by strCustomizeText. If bQuickCustomize is also TRUE, the menu displays the Add or Remove Buttons option.

The framework dynamically adds to the menu any buttons that do not fit in the toolbar area before the item that is specified by iCustomizeCmd. The chevron is displayed next to the down arrow.

`CMFCToolBar::EnableDocking`

Enables docking of the pane to the main frame.

virtual void EnableDocking(DWORD dwAlignment);

Parameters

dwAlignment
[in] Specifies the docking alignment to enable.

Remarks

This method extends the base class implementation, CBasePane::EnableDocking, by setting the CBasePane::m_dwControlBarStyle data member to AFX_CBRS_FLOAT. This method then passes dwAlignment to the base class implementation.

`CMFCToolBar::EnableLargeIcons`

Enables or disables large icons on toolbar buttons.

void EnableLargeIcons(BOOL bEnable);

Parameters

bEnable
[in] TRUE to enable large icons, FALSE to disable large icons.

Remarks

By default, large icons are enabled.

`CMFCToolBar::EnableQuickCustomization`

Enables or disables the quick customization of toolbars so that the user can press the Alt key and drag a button to a new location.

static void EnableQuickCustomization(BOOL bEnable=TRUE);

Parameters

bEnable
[in] TRUE to enable quick customization, FALSE to disable quick customization.

`CMFCToolBar::EnableReflections`

Enables or disables command reflection.

void EnableReflections(BOOL bEnable = TRUE);

Parameters

bEnable
[in] TRUE to enable command reflection; FALSE to disable command reflection.

Remarks

Call this method to enable command reflection for toolbar buttons that contain embedded controls, such as combo boxes.

For more information about command reflection, see TN062: Message Reflection for Windows Controls.

`CMFCToolBar::EnableTextLabels`

Enables or disables text labels under toolbar button images.

void EnableTextLabels(BOOL bEnable=TRUE);

Parameters

bEnable
TRUE if text labels appear under toolbar button images; otherwise FALSE.

Remarks

If text labels are enabled, all buttons on the toolbar are enlarged to provide space for the labels to be displayed under the images. The customization dialog box has a Show text label check-box on the Toolbars page. When the user selects a toolbar and checks this option, the framework calls EnableTextLabels for the selected toolbar. You can disable the check-box for an object derived from CMFCToolBar by returning FALSE from CMFCToolBar::AllowChangeTextLabels .

`CMFCToolBar::FromHandlePermanent`

Retrieves a pointer to the CMFCToolBar object that contains the given window handle.

static CMFCToolBar* __stdcall FromHandlePermanent(HWND hwnd);

Parameters

hwnd
[in] The window handle to look for.

Return Value

A pointer to the CMFCToolBar object that contains the given window handle, or NULL if no corresponding CMFCToolBar object exists.

Remarks

This shared method examines each toolbar in the application for the CMFCToolBar object that contains the given window handle.

`CMFCToolBar::GetAllButtons`

Returns a read-only list of buttons in a toolbar.

const CObList& GetAllButtons() const;

Return Value

A constant reference to a CObList Class object, which contains a collection of CMFCToolBarButton Class objects.

`CMFCToolBar::GetAllToolbars`

Returns a read-only list of all toolbars in the application.

static const CObList& GetAllToolbars();

Return Value

A const reference to a CObList Class object that contains a collection of CMFCToolBar objects.

`CMFCToolBar::GetBasicCommands`

Returns a read-only list of the basic commands defined in the application.

static const CList<UINT,UINT>& GetBasicCommands();

Return Value

A const reference to a CList Class object that contains a collection of basic commands.

Remarks

Add basic commands by calling CMFCToolBar::AddBasicCommand or CMFCToolBar::SetBasicCommands.

`CMFCToolBar::GetButton`

Returns a pointer to the CMFCToolBarButton Class object at a specified index.

CMFCToolBarButton* GetButton(int iIndex) const;

Parameters

iIndex
[in] Specifies the index of the button to return.

Return Value

A pointer to the toolbar button if it exists; or NULL if there is no such button.

`CMFCToolBar::GetButtonInfo`

Returns the command ID, style, and image index of the button at a specified index.

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

Parameters

nIndex
[in] Specifies the index of the button in the list of buttons on the toolbar.

nID
[out] The command ID of a button.

nStyle
[out] The style of the button.

iImage
[out] The index of the image for the button.

Remarks

The GetButtonInfo method finds a toolbar button at the specified index and retrieves the command ID, style, and image index of the button.

If the button at the specified index does not exist, the framework sets nID and nStyle to 0, and iImage to -1 when the method returns.

`CMFCToolBar::GetButtonSize`

Returns the dimensions of each button on the toolbar.

CSize GetButtonSize() const;

Return Value

A CSize Class object that specifies the dimensions of each button on the toolbar.

Remarks

Call CMFCToolBar::SetSizes or CMFCToolBar::SetLockedSizes to set the dimensions of each button on the toolbar.

`CMFCToolBar::GetButtonStyle`

Returns the current style of the toolbar button that is located at the specified index.

UINT GetButtonStyle(int nIndex) const;

Parameters

nIndex
[in] Specifies the index of a toolbar button.

Return Value

A value that specifies the style of the toolbar button. . See ToolBar Control Styles for a list of possible styles.

Remarks

Call CMFCToolBar::SetButtonStyle to set the style of a toolbar button

`CMFCToolBar::GetButtonText`

Returns the text label of a button that has a specified index.

CString GetButtonText(int nIndex) const;

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

`CMFCToolBar::GetCommandButtons`

Returns a list of buttons that have a specified command ID from all toolbars in the application.

static int GetCommandButtons(
    UINT uiCmd,
    CObList& listButtons);

Parameters

uiCmd
[in] The command ID of the buttons.

listButtons
[out] A reference to a CObList Class object that receives the list of toolbar buttons.

Return Value

The number of buttons that have the specified command ID.

`CMFCToolBar::GetCount`

Returns the number of buttons and separators on the toolbar.

int GetCount() const;

Return Value

The number of buttons and separators on the toolbar.

`CMFCToolBar::GetCustomizeButton`

Retrieves a pointer to the CMFCCustomizeButton object that is associated with the toolbar.

CMFCCustomizeButton* GetCustomizeButton();

Return Value

A pointer to the CMFCCustomizeButton object that is associated with the toolbar.

Remarks

This method retrieves the Customize button that appears at the end of the toolbar. Use the CMFCToolBar::EnableCustomizeButton method to add the Customize button to your toolbar.

You can call the CMFCToolBar::IsExistCustomizeButton method to determine whether the toolbar contains a valid CMFCCustomizeButton object.

`CMFCToolBar::GetDefaultImage`

Returns the index of the default image for a toolbar button with a specified command ID.

static int GetDefaultImage(UINT uiID);

Parameters

BOOL GetIgnoreSetText() const;

Return Value

TRUE if calls to set button labels are ignored; otherwise, FALSE.

Remarks

`CMFCToolBar::GetImages`

Returns a pointer to the collection of default button images in the application.

static CMFCToolBarImages* GetImages();

Return Value

A pointer to the CMFCToolBarImages Class object that contains the collection of default images for all toolbars in the application.

Remarks

This shared method provides access to the collection of all default toolbar images for the application. Call the CMFCToolBar::LoadBitmap method to add images to the collection.

`CMFCToolBar::GetImageSize`

Returns the current size of toolbar button images.

CSize GetImageSize() const;

Return Value

A CSize Class object that represents the current size of toolbar button images.

`CMFCToolBar::GetImagesOffset`

Returns the index offset used to find the toolbar button images for this toolbar in the global list of toolbar button images.

int GetImagesOffset() const;

Return Value

The index offset of the toolbar images.

Remarks

All toolbar default images are stored in the global CMFCToolBarImages Class list. The images for each button in the toolbar are stored consecutively in that list. To compute the index of the image, add the index of the button in the toolbar to the offset of the beginning of the list of images for that toolbar button.

Call CMFCToolBar::ButtonToIndex to obtain the index of a toolbar button given a pointer to the button.

Call CMFCToolBar::GetImages to obtain a pointer to the collection of toolbar images.

`CMFCToolBar::GetInvalidateItemRect`

Retrieves the region of the client area that must be redrawn for the button at the given index.

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

Parameters

nIndex
[in] The index of the button for which to retrieve the client area.

lpRect
[out] A pointer to a RECT object that receives the region of the client area.

Remarks

The lpRect parameter must not be NULL. If no button exists at the provided index, lpRect receives a RECT object that is initialized to zero.

`CMFCToolBar::GetItemID`

Returns the command ID of the toolbar button at a specified index.

UINT GetItemID(int nIndex) const;

Parameters

nIndex
[in] Specifies the index of the toolbar button.

Return Value

The command ID of the toolbar button; or zero if the button with the specified index does not exist.

`CMFCToolBar::GetItemRect`

Returns the bounding rectangle of the button at a specified index.

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

Parameters

nIndex
[in] Specifies the index of a toolbar button.

lpRect
[out] A pointer to CRect object that receives the coordinates of the image bounding rectangle.

Remarks

The CRect object to which lpRect points is set to 0 if a button at the specified index does not exist.

Example

The following example demonstrates how to use the GetItemRect method of the CMFCToolBar class. This code snippet is part of the IE Demo sample.

CMFCToolBar m_wndToolBar;

CRect rectToolBar;
m_wndToolBar.GetItemRect(0, &rectToolBar);

`CMFCToolBar::GetLargeColdImages`

Returns a pointer to the collection of large cold toolbar button images in the application.

static CMFCToolBarImages* GetLargeColdImages();

Return Value

A pointer to the collection of large cold images.

Remarks

Cold images are the images that are used when the user is not interacting with the toolbar buttons. Call CMFCToolBar::LoadBitmapEx to load the large cold images.

`CMFCToolBar::GetLargeDisabledImages`

Returns a pointer to the collection of large disabled toolbar button images in the application.

static CMFCToolBarImages* GetLargeDisabledImages();

Return Value

A pointer to the collection of large disabled toolbar button images.

Remarks

Large images are large versions of the regular toolbar button images. Call CMFCToolBar::LoadBitmapEx or CMFCToolBar::LoadBitmap to load the large images.

`CMFCToolBar::GetLargeImages`

Returns a pointer to the collection of large toolbar button images in the application.

static CMFCToolBarImages* GetLargeImages();

Return Value

A pointer to the collection of large toolbar button images.

Remarks

Large images are large versions of the regular toolbar button images. Call CMFCToolBar::LoadBitmapEx to load the large images.

`CMFCToolBar::GetLockedColdImages`

Returns a pointer to the collection of locked cold images in the toolbar.

CMFCToolBarImages* GetLockedColdImages();

Return Value

A pointer to the collection of locked cold images, or NULL if the toolbar is not locked.

Remarks

Locked images are versions of the regular toolbar button images that the framework uses when the user cannot customize the toolbar. Cold images are the images that are used when the user is not interacting with the toolbar buttons.

This method returns NULL if the toolbar is not locked. This method also generates an assertion failure in Debug builds if the toolbar is not locked. For more information about locked toolbars, see CMFCToolBar::IsLocked.

Call the CMFCToolBar::LoadBitmapEx method to load the locked cold images.

`CMFCToolBar::GetLockedDisabledImages`

Returns a pointer to the collection of locked disabled images in the toolbar.

CMFCToolBarImages* GetLockedDisabledImages();

Return Value

A pointer to the collection of locked disabled images, or NULL if the toolbar is not locked.

Remarks

Locked images are versions of the regular toolbar button images that the framework uses when the user cannot customize the toolbar. Disabled images are the images that the framework uses when a button has the TBBS_DISABLED style.

Call the CMFCToolBar::LoadBitmapEx method to load the locked disabled images.

`CMFCToolBar::GetLockedImages`

Returns a pointer to the collection of locked button images in the toolbar.

CMFCToolBarImages* GetLockedImages();

Return Value

A pointer to the collection of locked toolbar button images, or NULL if the toolbar is not locked.

Remarks

Locked images are versions of the regular toolbar button images that the framework uses when the user cannot customize the toolbar.

`CMFCToolBar::GetLockedImageSize`

Returns the default size of locked toolbar images.

CSize GetLockedImageSize() const;

Return Value

A CSize structure that specifies the size of locked toolbar images or an empty CSize structure if the toolbar is not locked.

Remarks

Locked images are versions of the regular toolbar button images that the framework uses when the user cannot customize the toolbar.

This method returns a CSize structure with zero width and zero height if the toolbar is not locked. This method also generates an assertion failure in Debug builds if the toolbar is not locked. For more information about locked toolbars, see CMFCToolBar::IsLocked.

Call the CMFCToolBar::SetLockedSizes method to specify the locked image size.

`CMFCToolBar::GetLockedMenuImages`

Returns a pointer to the collection of locked toolbar menu images in the toolbar.

CMFCToolBarImages* GetLockedMenuImages();

Return Value

A pointer to the collection of locked toolbar menu images, or NULL if the toolbar is not locked.

Remarks

Locked images are versions of the regular toolbar menu images that the framework uses when the user cannot customize the toolbar.

Call the CMFCToolBar::LoadBitmapEx method to load the locked menu images.

`CMFCToolBar::GetMenuButtonSize`

Returns the size of menu buttons in the application.

static CSize GetMenuButtonSize();

Return Value

A CSize object that represents the size of menu buttons, in pixels.

Remarks

The size of menu buttons on toolbars is maintained as a global variable and can be retrieved by this static method.

Call CMFCToolBar::SetMenuSizes to set this global variable.

`CMFCToolBar::GetMenuImages`

Returns a pointer to the collection of menu button images in the application.

static CMFCToolBarImages* GetMenuImages();

Return Value

A pointer to the collection of menu images.

Remarks

Call the CMFCToolBar::LoadBitmapEx method to load the menu images.

Call the CMFCToolBar::SetMenuSizes method to set the size of buttons and their images.

`CMFCToolBar::GetMenuImageSize`

Returns the size of menu button images in the application.

static CSize GetMenuImageSize();

Return Value

A CSize object that represents the size of menu images.

Remarks

This method returns the size of images on toolbar menu buttons that is maintained as a global variable. Call CMFCToolBar::SetMenuSizes to set this global variable.

`CMFCToolBar::GetOrigButtons`

Retrieves the collection of non-customized buttons of the toolbar.

const CObList& GetOrigButtons() const;

Return Value

A reference to the list of non-customized buttons of the toolbar.

Remarks

The framework creates a copy of toolbar buttons before they are customized by the user. The CMFCToolBar::SetButtons method adds a copy of each button in the provided array to the list of original buttons. The CMFCToolBar::RestoreOriginalState method restores the original state of the toolbar by loading it from the resource file.

To set the list of original buttons for your toolbar, call the CMFCToolBar::SetOrigButtons method.

`CMFCToolBar::GetOrigResetButtons`

Retrieves the collection of non-customized reset buttons of the toolbar.

const CObList& GetOrigResetButtons() const;

Return Value

A reference to the list of non-customized reset buttons of the toolbar.

Remarks

When the user selects the Reset button during customization mode, the framework uses this method to restore buttons that were removed from the toolbar.

The CMFCToolBar::SetButtons method adds a copy of each toolbar button to the list of original reset buttons after it calls the CMFCToolBar::OnReset method. You can override the CMFCToolBar::OnReset method to customize the appearance of buttons after the user presses the Reset button.

`CMFCToolBar::GetResourceID`

Retrieves the resource ID of the toolbar.

UINT GetResourceID() const;

Return Value

The resource ID of the toolbar.

Remarks

Call the CMFCToolBar::LoadToolBarEx method to set the resource ID of the toolbar.

`CMFCToolBar::GetRouteCommandsViaFrame`

Determines which object, the parent frame or the owner, sends commands to the toolbar.

BOOL GetRouteCommandsViaFrame();

Return Value

Nonzero if the parent frame sends commands to the toolbar; 0 if the owner sends commands to the toolbar.

Remarks

By default, the parent frame sends commands to the toolbar. Call CMFCToolBar::SetRouteCommandsViaFrame to change this behavior.

If this method returns a nonzero value, you can retrieve a pointer to the parent frame object by using the CMFCToolBar::GetCommandTarget method. See the VisualStudioDemo sample for an example that uses this method.

`CMFCToolBar::GetRowHeight`

Returns the height of toolbar buttons.

virtual int GetRowHeight() const;

Return Value

The height of toolbar buttons, in pixels.

Remarks

The framework calls this method to calculate toolbar layout. Override this method in a derived class to specify a different height for your toolbar.

`CMFCToolBar::GetShowTooltips`

Specifies whether tool tips are displayed for toolbar buttons.

static BOOL GetShowTooltips();

Return Value

TRUE if tool tips are shown for toolbar buttons; otherwise FALSE.

Remarks

By default tool tips are shown. You can change this static flag by calling CMFCToolBar::SetShowTooltips.

`CMFCToolBar::GetSiblingToolBar`

Retrieves the sibling of the toolbar.

CMFCToolBar* GetSiblingToolBar();

Return Value

A pointer to the sibling toolbar.

Remarks

For more information about how to enable the Show Buttons on One Row and Show Buttons on Two Rows buttons, see CMFCToolBar::SetSiblingToolBar.

`CMFCToolBar::GetUserImages`

Returns a pointer to the collection of user-defined toolbar button images in the application.

static CMFCToolBarImages* GetUserImages();

Return Value

A pointer to the collection of user-defined toolbar button images for all toolbars in the application.

Remarks

Call the CMFCToolBar::SetUserImages method to set the collection of user-defined images in the application.

`CMFCToolBar::HitTest`

Returns the index of the toolbar button that is located at the specified position.

virtual int HitTest(CPoint point);

Parameters

point
[in] The point to be tested, in client coordinates.

Return Value

The index of the button that is located at the specified position, or -1 if there is no such button or the button is a separator.

`CMFCToolBar::InsertButton`

Inserts a button into the toolbar.

virtual int InsertButton(
    const CMFCToolBarButton& button,
    INT_PTR iInsertAt=-1);

virtual int InsertButton(
    CMFCToolBarButton* pButton,
    int iInsertAt=-1);

Parameters

button
[in] Specifies the button to insert.

iInsertAt
[in] Specifies the zero-based position to insert the button at.

Return Value

The position at which the button was inserted or -1 if an error occurs.

Remarks

If iInsertAt is -1, this method adds the button to the end of the list of toolbar buttons.

Call the CMFCToolBar::InsertSeparator method to insert a separator into the toolbar.

`CMFCToolBar::InsertSeparator`

Inserts a separator into the toolbar.

virtual int InsertSeparator(INT_PTR iInsertAt=-1);

Parameters

iInsertAt
[in] Specifies the zero-based position to insert the separator at. This parameter must be larger than 0.

Return Value

The position at which the separator was inserted or -1 if an error occurs.

Remarks

Call this method to insert a separator between two existing buttons. If iInsertAt is -1, this method adds the separator to the end of the list of toolbar buttons.

You cannot use this method to add a separator to an empty toolbar.

Call the CMFCToolBar::InsertButton method to insert a button into the toolbar.

`CMFCToolBar::InvalidateButton`

Invalidates the client area of the toolbar button that exists at the provided index.

CMFCToolBarButton* InvalidateButton(int nIndex);

Parameters

nIndex
[in] The zero-based index of the button in the toolbar.

Return Value

A pointer to the CMFCToolBarButton object that exists at the provided index or NULL if no such object exists.

Remarks

The framework calls this method when it updates the client area that is associated with a toolbar button. It calls the CWnd::InvalidateRect method with the client rectangle of the CMFCToolBarButton object that exists at the provided index.

`CMFCToolBar::IsAddRemoveQuickCustomize`

Determines whether a user can add or remove toolbar buttons by using the Customize menu option.

BOOL IsAddRemoveQuickCustomize();

Return Value

TRUE if a user can use the Customize menu option to modify the toolbar; otherwise, FALSE.

Remarks

`CMFCToolBar::IsAltCustomizeMode`

Specifies whether quick customization is being used to drag a button. When quick customization is enabled, a user can press and hold the Alt key and drag a button to a new location.

static BOOL __stdcall IsAltCustomizeMode();

Return Value

TRUE if quick customization is being used to drag a button; otherwise, FALSE.

Remarks

`CMFCToolBar::IsAutoGrayInactiveImages`

Specifies whether the automatic generation of inactive (non-highlighted) button images is enabled.

static BOOL IsAutoGrayInactiveImages();

Return Value

TRUE if the option to automatically dim inactive images is enabled; otherwise FALSE.

Remarks

You can enable or disable automatic dimming of inactive images by calling CMFCToolBar::AutoGrayInactiveImages.

`CMFCToolBar::IsBasicCommand`

Determines whether a command is on the list of basic commands.

static BOOL IsBasicCommand(UINT uiCmd);

Parameters

uiCmd
[in] Specifies the command to check.

Return Value

TRUE if the specified command belongs to the list of basic commands; otherwise FALSE.

Remarks

This static method determines whether the command specified by uiCmd belongs to the global list of basic commands. You can change the list of basic commands by calling CMFCToolBar::AddBasicCommand or CMFCToolBar::SetBasicCommands.

`CMFCToolBar::IsButtonExtraSizeAvailable`

Determines whether the toolbar can display buttons that have extended borders.

virtual BOOL IsButtonExtraSizeAvailable() const;

Return Value

TRUE if the bar can display buttons with the extra border size; otherwise FALSE.

Remarks

The toolbar object returns TRUE if it can display buttons that have extended borders. A toolbar button calls this method when it handles the CMFCToolBarButton::OnChangeParentWnd notification and will set its internal extra border size flag accordingly. This internal flag may be retrieved later by calling CMFCToolBarButton::IsExtraSize.

Override this method in a class derived from CMFCToolBar and return TRUE if your bar can display the toolbar buttons with the extra border size and return FALSE otherwise. The default implementation returns TRUE.

`CMFCToolBar::IsButtonHighlighted`

Determines whether the specified button is highlighted.

BOOL IsButtonHighlighted(int iButton) const;

Parameters

iButton
[in] Specifies the index of a toolbar button.

Return Value

TRUE if the specified button is highlighted; otherwise, FALSE.

Remarks

`CMFCToolBar::IsCommandPermitted`

Determines whether a command is permitted.

static BOOL IsCommandPermitted(UINT uiCmd);

Parameters

uiCmd
[in] Specifies the command to check.

Return Value

TRUE if the specified command is permitted; otherwise FALSE.

Remarks

This static method determines whether the command specified by uiCmd belongs to the global list of non-permitted commands.

You can change the list of non-permitted commands by calling CMFCToolBar::SetNonPermittedCommands.

`CMFCToolBar::IsCommandRarelyUsed`

Determines whether a command is rarely used.

static BOOL IsCommandRarelyUsed(UINT uiCmd);

Parameters

uiCmd
[in] Specifies the command to check.

Return Value

TRUE if the specified command is rarely used; otherwise FALSE.

Remarks

The IsCommandRarelyUsed method returns FALSE when one or more of the following conditions occur:

The specified command belongs to the list of basic commands
The specified command is one of the standard commands
The framework is in customization mode
The list of basic commands is empty
More than 20% of command calls are calls to the specified command.

`CMFCToolBar::IsCustomizeMode`

Specifies whether the toolbar framework is in customization mode.

static BOOL IsCustomizeMode();

Return Value

TRUE if the framework is in customization mode; otherwise FALSE.

Remarks

You can toggle customization mode by calling CMFCToolBar::SetCustomizeMode.

The framework changes the mode when the user invokes the customization dialog box ( CMFCToolBarsCustomizeDialog Class).

`CMFCToolBar::IsDragButton`

Determines whether a toolbar button is being dragged.

BOOL IsDragButton(const CMFCToolBarButton* pButton) const;

Parameters

pButton
[in] Pointer to a toolbar button.

Return Value

TRUE if the specified button is being dragged; otherwise, FALSE.

Remarks

`CMFCToolBar::IsExistCustomizeButton`

Determines whether the toolbar contains the Customize button.

BOOL IsExistCustomizeButton();

Return Value

TRUE if the toolbar contains the Customize button; otherwise FALSE.

Remarks

If this method returns TRUE, the CMFCToolBar::GetCustomizeButton method returns a pointer to the Customize button that appears at the end of the toolbar.

Use the CMFCToolBar::EnableCustomizeButton method to add the Customize button to your toolbar.

`CMFCToolBar::IsFloating`

Determines whether the toolbar is floating.

virtual BOOL IsFloating() const;

Return Value

TRUE if the toolbar is floating; otherwise, FALSE.

`CMFCToolBar::IsLargeIcons`

Specifies whether toolbars in the application currently display large icons.

static BOOL IsLargeIcons();

Return Value

TRUE if the application is using large icons; otherwise FALSE.

Remarks

Call CMFCToolBar::SetLargeIcons to toggle between large icons and regular icons.

The framework automatically changes the mode when the user toggles the Large icons check-box on the Options page of the Customization dialog box.

`CMFCToolBar::IsLastCommandFromButton`

Determines whether the most recently executed command was sent from the specified toolbar button.

static BOOL IsLastCommandFromButton(CMFCToolBarButton* pButton);

Parameters

pButton
[in] Pointer to button.

Return Value

TRUE if the last command was sent from the button that pButton specifies; otherwise FALSE.

Remarks

This method obtains a pointer to a MSG Structure by calling CWnd::GetCurrentMessage. It then compares the HWND of the button with the MSG::lParam and MSG::hwnd members to determine whether the button was the source of the command.

`CMFCToolBar::IsLocked`

Determines whether the toolbar is locked.

BOOL IsLocked() const;

Return Value

TRUE if the toolbar is locked; otherwise, FALSE.

Remarks

This method returns TRUE when the user cannot perform customization tasks such as repositioning toolbar buttons.

Locked toolbars use separate image lists. For more information about these image lists, see CMFCToolBar::LoadBitmapEx.

`CMFCToolBar::IsOneRowWithSibling`

Determines whether the toolbar and its sibling toolbar are positioned on the same row.

BOOL IsOneRowWithSibling();

Return Value

TRUE if the toolbar and its sibling are positioned on the same row; otherwise FALSE.

Remarks

The CMFCCustomizeButton::CreatePopupMenu method calls this method to determine how to show the Customize pop-up menu. If this method returns TRUE, the framework displays the Show Buttons on One Row button. Otherwise, the framework displays the Show Buttons on Two Rows button.

You typically do not have to use this method. To enable the Show Buttons on One Row or Show Buttons on Two Rows buttons, call CMFCToolBar::SetSiblingToolBar.

`CMFCToolBar::IsResourceChanged`

virtual BOOL IsResourceChanged() const;

Return Value

Remarks

`CMFCToolBar::IsSibling`

BOOL IsSibling();

Return Value

Remarks

`CMFCToolBar::IsUserDefined`

Specifies whether the toolbar is user-defined.

BOOL IsUserDefined() const;

Return Value

TRUE if the toolbar was created by the user; otherwise FALSE.

`CMFCToolBar::LoadBitmap`

Loads toolbar images from application resources.

virtual BOOL LoadBitmap(
    UINT uiResID,
    UINT uiColdResID=0,
    UINT uiMenuResID=0,
    BOOL bLocked=FALSE,
    UINT uiDisabledResID=0,
    UINT uiMenuDisabledResID=0);

Parameters

uiResID
[in] The resource ID of the bitmap that refers to the hot toolbar images.

uiColdResID
[in] The resource ID of the bitmap that refers to the cold toolbar images.

uiMenuResID
[in] The resource ID of the bitmap that refers to the regular menu images.

bLocked
[in] TRUE to lock the toolbar; otherwise FALSE.

uiDisabledResID
[in] The resource ID of the bitmap that refers to the disabled toolbar images.

uiMenuDisabledResID
[in] The resource ID of the bitmap that refers to the disabled menu images.

Return Value

Nonzero if the method succeeds; otherwise 0.

Remarks

The CMFCToolBar::LoadToolBarEx method calls this method to load the images that are associated with the toolbar. Override this method to perform custom loading of image resources.

Call the LoadBitmapEx method to load additional images after you create the toolbar.

`CMFCToolBar::LoadBitmapEx`

virtual BOOL LoadBitmapEx(
    CMFCToolBarInfo& params,
    BOOL bLocked = FALSE);

Parameters

[in] params
[in] bLocked\

Return Value

Remarks

`CMFCToolBar::LoadLargeIconsState`

static BOOL __stdcall LoadLargeIconsState(LPCTSTR lpszProfileName = NULL);

Parameters

[in] lpszProfileName\

Return Value

Remarks

`CMFCToolBar::LoadParameters`

Loads global toolbar options from the Windows registry.

static BOOL LoadParameters(LPCTSTR lpszProfileName=NULL);

Parameters

lpszProfileName
[in] Specifies the relative path of the Windows registry key.

Return Value

Nonzero if the method succeeds; otherwise 0.

Remarks

This method loads global parameters such as the menu animation type, the menu shadow style, and whether to display large icons from the Windows registry.

The CWinAppEx::LoadState method calls this method as a part of the initialization process of the application.

`CMFCToolBar::LoadState`

Loads the toolbar state information from the Windows registry.

virtual BOOL LoadState(
    LPCTSTR lpszProfileName=NULL,
    int nIndex=-1,
    UINT uiID=(UINT)-1);

Parameters

lpszProfileName
[in] Specifies the relative path of the Windows registry key.

nIndex
[in] Specifies the control ID of the toolbar.

uiID
[in] Specifies the resource ID of the toolbar.

Return Value

Nonzero if the method succeeds; otherwise 0.

Remarks

The framework calls this method as a part of the initialization process of the application. For more information, see CWinAppEx::LoadState.

`CMFCToolBar::LoadToolBar`

Loads the toolbar from application resources.

virtual BOOL LoadToolBar(
    UINT uiResID,
    UINT uiColdResID=0,
    UINT uiMenuResID=0,
    BOOL bLocked=FALSE,
    UINT uiDisabledResID=0,
    UINT uiMenuDisabledResID=0,
    UINT uiHotResID=0);

Parameters

uiResID
[in] The resource ID of the toolbar.

uiColdResID
[in] The resource ID of the bitmap that refers to the cold toolbar images.

uiMenuResID
[in] The resource ID of the bitmap that refers to the regular menu images.

bLocked
[in] A Boolean value that specifies whether the toolbar is locked or not. If this parameter is TRUE, the toolbar is locked. Otherwise, the toolbar is not locked.

uiDisabledResID
[in] The resource ID of the bitmap that refers to the disabled toolbar images.

uiMenuDisabledResID
[in] The resource ID of the bitmap that refers to the disabled menu images.

uiHotResID
[in] The resource ID of the bitmap that refers to the hot toolbar images.

Return Value

Nonzero if the method succeeds; otherwise 0.

Remarks

The framework calls this method during initialization to load the images that are associated with the toolbar.

Example

The following example demonstrates how to use the LoadToolBar method in the CMFCToolBar class. This code snippet is part of the IE Demo sample.

CMFCToolBar m_wndToolBar;

// The this pointer points to CMainFrame class which extends the CFrameWnd class.
if (!m_wndToolBar.CreateEx(this, TBSTYLE_TRANSPARENT) ||
    !m_wndToolBar.LoadToolBar(IDR_MAINFRAME, uiToolbarColdID, uiMenuID,
                              FALSE /* Not locked */, 0, 0, uiToolbarHotID))
{
   TRACE0("Failed to create toolbar\n");
   return -1; // fail to create
}

`CMFCToolBar::LoadToolBarEx`

Loads the toolbar from application resources by using the CMFCToolBarInfo helper class to enable the application to use large images.

virtual BOOL LoadToolBarEx(
    UINT uiToolbarResID,
    CMFCToolBarInfo& params,
    BOOL bLocked=FALSE);

Parameters

uiToolbarResID
[in] The resource ID of the toolbar.

params
[in] A reference to a CMFCToolBarInfo object that contains the resource IDs for the toolbar images.

bLocked
[in] A Boolean value that specifies whether the toolbar is locked or not. If this parameter is TRUE, the toolbar is locked. Otherwise, the toolbar is not locked.

Return Value

Nonzero if the method succeeds; otherwise 0.

Remarks

Call this method to load toolbar images from the application resources.

`CMFCToolBar::m_dblLargeImageRatio`

Specifies the ratio between the dimension (height or width) of large images and the dimension of regular images.

AFX_IMPORT_DATA static double m_dblLargeImageRatio;

Remarks

The default ratio is 2. You can change this value to make large toolbar images larger or smaller.

The framework uses this data member when you do not specify a set of large images. For example, if you provide only the set of small images with size 16x16 and want the large images to have the size 24x24, set this data member to 1.5.

`CMFCToolBar::NextMenu`

virtual BOOL NextMenu();

Return Value

Remarks

`CMFCToolBar::OnBeforeRemoveButton`

virtual BOOL OnBeforeRemoveButton(
    CMFCToolBarButton* pButton,
    DROPEFFECT dropEffect);

Parameters

pButton
[in] Unused.

dropEffect
[in] Unused.

Return Value

Remarks

`CMFCToolBar::OnChangeHot`

Called by the framework when a user selects a button on the toolbar.

virtual void OnChangeHot(int iHot);

Parameters

iHot
[in] Specifies the index of the toolbar button that is selected; or -1 if no toolbar button is selected.

Remarks

Override this method to process notifications that the user selected a button on a toolbar.

`CMFCToolBar::OnChangeVisualManager`

virtual void OnChangeVisualManager();

Remarks

`CMFCToolBar::OnFillBackground`

Called by the framework from CBasePane::DoPaint to fill the toolbar background.

virtual void OnFillBackground(CDC* pDC);

Parameters

pDC
[in] A pointer to a device context.

Remarks

CMFCToolBar::DoPaint calls this method when the background of a toolbar has been filled. The default implementation does nothing.

Override this method to draw custom background in derived classes.

`CMFCToolBar::OnGlobalFontsChanged`

virtual void OnGlobalFontsChanged();

Remarks

`CMFCToolBar::OnReset`

Restores the toolbar to its original state.

virtual void OnReset();

Remarks

Override this method to handle notification about a toolbar reset.

The default implementation does nothing. Override OnReset in a class derived from CMFCToolBar when the toolbar has dummy buttons that must be replaced when the toolbar returns to its original state.

`CMFCToolBar::OnSetAccData`

virtual BOOL OnSetAccData(long lVal);

Parameters

[in] lVal\

Return Value

Remarks

`CMFCToolBar::OnSetDefaultButtonText`

Restores the text of a toolbar button to its default state.

virtual BOOL OnSetDefaultButtonText(CMFCToolBarButton* pButton);

Parameters

pButton
[in] Points to a button, whose text is being set.

Return Value

TRUE ifthe text was successfully restored; otherwise FALSE.

Remarks

Override this method to process notifications that the text of a toolbar button is being changed to its default.

The default implementation loads the text of a button from the application resources.

`CMFCToolBar::OnUserToolTip`

Called by the framework when the tooltip for a button is about to be displayed.

virtual BOOL OnUserToolTip(
    CMFCToolBarButton* pButton,
    CString& strTTText) const;

Parameters

pButton
[in] Points to a toolbar button for which a tooltip is to be displayed.

strTTText
[out] A reference to CString object that receives the text of the tooltip.

Return Value

TRUE if strTTText was populated with tooltip text; otherwise FALSE.

Remarks

The framework calls this method when the tooltip for a toolbar button is about to be displayed. If OnUserToolTip returns TRUE, the framework displays a tooltip that contains the text returned by OnUserToolTip in strTTText. Otherwise, the tooltip contains the button text.

Override OnUserToolTip to customize tool tips of toolbar buttons. The default implementation calls CMFCToolBar::OnUserToolTip to obtain the tooltip text.

`CMFCToolBar::PrevMenu`

virtual BOOL PrevMenu();

Return Value

Remarks

`CMFCToolBar::ProcessCommand`

Posts a WM_COMMAND message to the window that owns the toolbar.

BOOL ProcessCommand(CMFCToolBarButton* pButton);

Parameters

pButton
[in] Pointer to a button on the toolbar.

Return Value

This method should always return TRUE. MFC uses FALSE values internally.

Remarks

This method posts a WM_COMMAND message to the window that owns the toolbar by calling CWnd::PostMessage and passing the command ID of the specified button as the wParam parameter.

Use the ON_COMMAND macro to map the WM_COMMAND message to a member function.

`CMFCToolBar::RemoveAllButtons`

Removes all buttons and separators from the toolbar.

virtual void RemoveAllButtons();

Remarks

The framework calls this method when it recreates or destroys a toolbar.

`CMFCToolBar::RemoveButton`

Removes from the toolbar the button that has the specified index.

virtual BOOL RemoveButton(int iIndex);

Parameters

iIndex
[in] Specifies the zero-based index of the button to remove.

Return Value

TRUE if the method succeeds, or FALSE if the specified index is invalid or the index refers to the Customize button.

Remarks

This method updates additional toolbar attributes that are affected by the removal of the button. For example, this method removes nonessential separators from the toolbar and rebuilds the table of shortcut keys.

For more information about the Customize button, see CMFCToolBar::EnableCustomizeButton.

`CMFCToolBar::RemoveStateFromRegistry`

Deletes the state information for the toolbar from the Windows registry.

virtual BOOL RemoveStateFromRegistry(
    LPCTSTR lpszProfileName=NULL,
    int nIndex=-1,
    UINT uiID=(UINT)-1);

Parameters

lpszProfileName
[in] Specifies the registry key where the state information is located.

nIndex
[in] The control ID of the toolbar.

uiID
[in] The resource ID of the toolbar. If this parameter is -1, this method uses the CWnd::GetDlgCtrlID method to retrieve the resource ID.

Return Value

Nonzero if the method succeeds; otherwise 0.

Remarks

The framework calls this method when it deletes a user-defined toolbar.

Override this method if you store additional state information in the Windows registry.

`CMFCToolBar::ReplaceButton`

Replaces a toolbar button with another toolbar button.

int ReplaceButton(
    UINT uiCmd,
    const CMFCToolBarButton& button,
    BOOL bAll=FALSE);

Parameters

uiCmd
[in] The command ID of the button to replace.

button
[in] A reference to the CMFCToolBarButton to insert.

bAll
[in] A Boolean value that specifies whether to replace all buttons that have the command ID specified by uiCmd. If this parameter is TRUE, all buttons that have the specified command ID are replaced. Otherwise, the first button is replaced.

Return Value

The number of buttons that are replaced. This method returns 0 if a button with the specified command ID does not exist on the toolbar.

Remarks

Call this method when you want to add toolbar buttons that cannot be loaded from resources. You can create a placeholder button at design-time and replace that button with a custom button when you initialize the toolbar. See the VisualStudioDemo sample for an example that uses this method.

Example

The following example demonstrates how to use the ReplaceButton method in the CMFCToolBar class. This code snippet is part of the IE Demo sample.

CMFCToolBar m_wndToolBar;

// CMenu menuHistory
// CString str
m_wndToolBar.ReplaceButton(ID_GO_BACK,
                           CMFCToolBarMenuButton(ID_GO_BACK, menuHistory,
                                                 GetCmdMgr()->GetCmdImage(ID_GO_BACK), str));

`CMFCToolBar::ResetAll`

Restores all toolbars to their original states.

static void __stdcall ResetAll();

Remarks

This method calls the CMFCToolBar::RestoreOriginalState method on each toolbar in the application that can be restored. It uses the CMFCToolBar::CanBeRestored method to determine whether a toolbar can be restored.

`CMFCToolBar::ResetAllImages`

Clears all toolbar image collections in the application.

static void __stdcall ResetAllImages();

Remarks

This method clears the image collections that are initialized by the CMFCToolBar::LoadToolBar and CMFCToolBar::LoadBitmap methods.

`CMFCToolBar::ResetImages`

virtual void ResetImages();

Remarks

`CMFCToolBar::RestoreFocus`

virtual void RestoreFocus();

Remarks

`CMFCToolBar::RestoreOriginalState`

Restores the original state of a toolbar.

virtual BOOL RestoreOriginalState();

Return Value

TRUE if the method succeeds, or FALSE if the method fails or the toolbar is user-defined.

Remarks

This method loads the toolbar from the resource file by using the CMFCToolBar::LoadToolBar method.

The framework calls this method when the user chooses the Reset All button on the Toolbars page of a customization dialog box.

`CMFCToolBar::SaveParameters`

static BOOL __stdcall SaveParameters(LPCTSTR lpszProfileName = NULL);

Parameters

[in] lpszProfileName\

Return Value

Remarks

`CMFCToolBar::SaveState`

Saves the state information for the toolbar in the Windows registry.

virtual BOOL SaveState(
    LPCTSTR lpszProfileName=NULL,
    int nIndex=-1,
    UINT uiID=(UINT)-1);

Parameters

lpszProfileName
[in] Specifies the relative path of the Windows registry key.

nIndex
[in] The control ID of the toolbar.

uiID
[in] The resource ID of the toolbar.

Return Value

Nonzero if the method succeeds; otherwise 0.

Remarks

The framework calls this method when it saves the application state to the registry. For more information, see CWinAppEx::SaveState.

`CMFCToolBar::SetBasicCommands`

Sets the list of commands that are always displayed when a user opens a menu.

static void __stdcall SetBasicCommands(CList<UINT,UINT>& lstCommands);

Parameters

lstCommands
[in] A reference to a CList object that contains a collection of commands.

Remarks

A basic command is always displayed when the menu is opened. This method is meaningful when the user chooses to view recently used commands.

Use the CMFCToolBar::AddBasicCommand method to add a command to the list of basic commands. Use the CMFCToolBar::GetBasicCommands method to retrieve the list of basic commands that is used by your application.

See the Explorer sample for an example that uses this method.

`CMFCToolBar::SetButtonInfo`

Sets the command ID, style, and image ID of a toolbar button.

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

Parameters

nIndex
[in] The zero-based index of the button whose properties are set.

nID
[in] The command ID of the button.

nStyle
[in] The style of the button. See ToolBar Control Styles for the list of available toolbar button styles.

iImage
[in] The zero-based image index of the button (that is, the index in the collection of toolbar images).

Remarks

Call this method to set the properties of a toolbar button.

In Debug builds, this method generates an assertion failure if the index that is specified by nIndex is invalid.

Call the CMFCToolBar::SetButtonStyle method to set only the style of the button.

`CMFCToolBar::SetButtons`

Sets the buttons for the toolbar.

virtual BOOL SetButtons(
    const UINT* lpIDArray,
    int nIDCount,
    BOOL bRemapImages=TRUE);

Parameters

lpIDArray
[in] A pointer to the array of command IDs of the buttons to insert.

nIDCount
[in] The number of items in lpIDArray.

bRemapImages
[in] A Boolean value that specifies whether to associate the existing button images with the inserted buttons. If this parameter is TRUE, the images are remapped.

Return Value

Nonzero if the method succeeds; otherwise 0.

Remarks

Call this method to remove existing buttons from a toolbar and insert a collection of new buttons.

This method adds the Customize button to the toolbar and sends the AFX_WM_RESETTOOLBAR message to the parent window of the toolbar. For more information about the Customize button, see CMFCToolBar::EnableCustomizeButton.

`CMFCToolBar::SetButtonStyle`

Sets the style of the toolbar button at the given index.

virtual void SetButtonStyle(
    int nIndex,
    UINT nStyle);

Parameters

nIndex
[in] The zero-based index of the toolbar button whose style is to be set.

nStyle
[in] The style of the button. See ToolBar Control Styles for the list of available toolbar button styles.

Remarks

This method removes the TBBS_PRESSED style if nStyle is TBBS_DISABLED because the user cannot select a disabled button.

`CMFCToolBar::SetButtonText`

Sets the text label of a toolbar button.

BOOL SetButtonText(
    int nIndex,
    LPCTSTR lpszText);

Parameters

nIndex
[in] The index of the toolbar button.

lpszText
[in] The text label of the toolbar button. Must be non-null.

Return Value

TRUE if the method succeeds; otherwise FALSE.

Remarks

This method returns FALSE if the provided index does not refer to a valid toolbar button.

`CMFCToolBar::SetCommandUsageOptions`

Specifies when rarely used commands do not appear in the menu of the application.

static BOOL SetCommandUsageOptions(
    UINT nStartCount,
    UINT nMinUsagePercentage=5);

Parameters

nStartCount
[in] Specifies the number of times that commands must be executed before the framework shows only the basic and recently-used commands.

nMinUsagePercentage
[in] The percentage of times that a command must be executed to be considered a recently-used command.

Return Value

FALSE if nMinUsagePercentage is equal to or larger than 100; otherwise TRUE.

Remarks

Call this method to customize the algorithm that the framework uses to determine how basic and recently used menu items appear. For more information about basic commands, see CMFCToolBar::AddBasicCommand.

This class uses the CMFCCmdUsageCount class to track the usage count of commands. For more information about this class, see CMFCCmdUsageCount Class.

`CMFCToolBar::SetCustomizeMode`

Enables or disables customization mode for all toolbars in the application.

static BOOL __stdcall SetCustomizeMode(BOOL bSet=TRUE);

Parameters

bSet
[in] A Boolean value that specifies whether to enable or disable customization mode. Set this parameter to TRUE to enable customization mode or FALSE to disable it.

Return Value

TRUE if calling this method changes the customization mode; otherwise FALSE.

Remarks

This method adjusts the layout of and redraws each toolbar in the application. Call the CMFCToolBar::IsCustomizeMode method to determine whether the application is in customization mode,

`CMFCToolBar::SetGrayDisabledButtons`

Specifies whether unavailable buttons on the toolbar are dimmed, or whether button-unavailable images are used.

void SetGrayDisabledButtons(BOOL bGrayDisabledButtons);

Parameters

bGrayDisabledButtons
[in] A Boolean value that specifies how to display unavailable buttons. If this parameter is TRUE, the framework dims the buttons. Otherwise, the framework uses the collection of button-unavailable images.

Remarks

By default, unavailable buttons are dimmed.

`CMFCToolBar::SetHeight`

Sets the height of the toolbar.

void SetHeight(int cyHeight);

Parameters

cyHeight
[in] The height of the toolbar, in pixels.

Remarks

This method redraws the toolbar after it sets the height.

`CMFCToolBar::SetHelpMode`

static void __stdcall SetHelpMode(BOOL bOn = TRUE);

Parameters

[in] bOn\

Remarks

`CMFCToolBar::SetHot`

BOOL SetHot(CMFCToolBarButton* pMenuButton);

Parameters

[in] pMenuButton\

Return Value

Remarks

`CMFCToolBar::SetHotBorder`

Specifies whether toolbar buttons are hot-tracked.

void SetHotBorder(BOOL bShowHotBorder);

Parameters

bShowHotBorder
[in] A Boolean value that specifies whether to hot-track toolbar buttons. If this parameter is TRUE, the toolbar hot-tracks its buttons. Otherwise, the toolbar does not hot-track its buttons.

Remarks

If a button is hot-tracked, the framework highlights the button when the mouse moves across it. By default, each toolbar hot-tracks its buttons.

Call the CMFCToolBar::GetHotBorder method to determine whether the toolbar hot-tracks its buttons.

`CMFCToolBar::SetHotTextColor`

Sets the text color for hot toolbar buttons.

static void SetHotTextColor(COLORREF clrText);

Parameters

clrText
[in] Specifies the text color for toolbar buttons that are hot-tracked.

Remarks

For more information about hot-tracked toolbar buttons, see CMFCToolBar::GetHotBorder and CMFCToolBar::SetHotBorder.

`CMFCToolBar::SetIgnoreSetText`

void SetIgnoreSetText(BOOL bValue);

Parameters

[in] bValue\

Remarks

`CMFCToolBar::SetLargeIcons`

Specifies whether toolbar buttons display large icons.

static void SetLargeIcons(BOOL bLargeIcons=TRUE);

Parameters

bLargeIcons
[in] A Boolean value that specifies which icons to use. If this parameter is TRUE, the framework displays large icons. Otherwise, the framework displays regular icons.

Remarks

The framework calls this method when the user changes the state of the Large Icons check box in the Options tab of the Customize dialog box. This method resizes all toolbars in the application.

By default, the framework displays regular icons.

For more information about the Customize dialog box, see CMFCToolBarsCustomizeDialog Class.

`CMFCToolBar::SetLockedSizes`

Sets the sizes of locked buttons and locked images on the toolbar.

void SetLockedSizes(
    SIZE sizeButton,
    SIZE sizeImage,
    BOOL bDontScale = FALSE);

Parameters

sizeButton
[in] Specifies the size of locked toolbar buttons.

sizeImage
[in] Specifies the size of locked toolbar images.

bDontScale
Specifies whether to scale or not locked toolbar images in high DPI mode.

Remarks

The default size of locked buttons is 23x22 pixels. The default size of locked images is 16x15 pixels.

Call the CMFCToolBar::GetLockedImageSize method to retrieve the size of locked images. Call the CMFCToolBar::GetButtonSize method to retrieve the size of locked toolbar buttons.

`CMFCToolBar::SetMaskMode`

void SetMaskMode(BOOL bMasked);

Parameters

[in] bMasked\

Remarks

`CMFCToolBar::SetMenuSizes`

Sets the size of toolbar menu buttons and their images.

static void __stdcall SetMenuSizes(
    SIZE sizeButton,
    SIZE sizeImage);

Parameters

sizeButton
[in] Specifies the size of toolbar buttons, in pixels.

sizeImage
[in] Specifies the size of toolbar images, in pixels.

Remarks

By default, menu buttons and their images have an undefined size.

Call the CMFCToolBar::GetMenuButtonSize method to determine the size of menu buttons and the CMFCToolBar::GetMenuImageSize method to determine the size of menu button images.

See the IEDemo and MSMoneyDemo samples for examples that use this method.

`CMFCToolBar::SetNonPermittedCommands`

Sets the list of commands that cannot be executed by the user.

static void SetNonPermittedCommands(CList<UINT,UINT>& lstCommands);

Parameters

lstCommands
[in] A reference to a CList object that contains the commands that cannot be executed by the user.

Remarks

Call this method to prevent the user from selecting certain commands. For example, you might want to prevent the user from selecting certain commands for security reasons. See the MDITabsDemo and MenuSubSet samples for examples that use this method.

This method clears the previous list of non-permitted commands. By default, the list of non-permitted commands is empty.

`CMFCToolBar::SetOneRowWithSibling`

Positions the toolbar and its sibling on the same row.

void SetOneRowWithSibling();

Remarks

The framework calls this method when the user selects the Show Buttons on One Row button.

Call the CMFCToolBar::SetSiblingToolBar method to enable the Show Buttons on One Row or Show Buttons on Two Rows buttons. If you call CMFCToolBar::SetSiblingToolBar for this toolbar, the sibling toolbar is moved to the row of this toolbar. Otherwise, this toolbar is moved to the row of the sibling.

The framework calls the CMFCToolBar::SetTwoRowsWithSibling method when the user selects the Show Buttons on Two Rows button.

`CMFCToolBar::SetOrigButtons`

void SetOrigButtons(const CObList& lstOrigButtons);

Parameters

[in] lstOrigButtons\

Remarks

`CMFCToolBar::SetPermament`

Specifies whether a user can close the toolbar.

void SetPermament(BOOL bPermament=TRUE);

Parameters

bPermament
[in] A Boolean value that specifies whether a user can close the toolbar. If this parameter is TRUE, a user cannot close the toolbar. Otherwise, a user can close the toolbar.

Remarks

By default, a user can close each toolbar.

Call the CMFCToolBar::CanBeClosed method to determine whether a user can close the toolbar.

`CMFCToolBar::SetRouteCommandsViaFrame`

Specifies whether the parent frame or the owner sends commands to the toolbar.

void SetRouteCommandsViaFrame(BOOL bValue);

Parameters

bValue
[in] If this parameter is TRUE, the parent frame sends commands to the toolbar. Otherwise, the owner sends commands to the toolbar.

Remarks

By default, the parent frame sends commands to the toolbar. Call the CMFCToolBar::GetRouteCommandsViaFrame method to determine whether the parent frame or the owner sends commands to the toolbar.

`CMFCToolBar::SetShowTooltips`

Specifies whether the framework displays tool tips.

static void SetShowTooltips(BOOL bValue);

Parameters

bValue
[in] If this parameter is TRUE, the framework shows tool tips. Otherwise, the framework hides tool tips.

Remarks

By default, the framework shows tool tips.

Call the CMFCToolBar::GetShowTooltips method to determine whether the framework shows tool tips.

`CMFCToolBar::SetSiblingToolBar`

Specifies the sibling of the toolbar.

void SetSiblingToolBar(CMFCToolBar* pBrotherToolbar);

Parameters

pBrotherToolbar
[in] A pointer to the sibling toolbar.

Remarks

This method enables the Show Buttons on One Row or Show Buttons on Two Rows buttons that are shown when the user displays the Customize pop-up menu. Call this method when you want to enable the user to specify whether related toolbars appear on the same row or on different rows.

Call this method after you enable the Customize button that appears on the toolbar. To enable the Customize button, call the CMFCToolBar::EnableCustomizeButton method.

To retrieve the sibling of a toolbar, call CMFCToolBar::GetSiblingToolBar.

`CMFCToolBar::SetSizes`

Specifies the sizes of buttons and images on all toolbars.

static void __stdcall SetSizes(
    SIZE sizeButton,
    SIZE sizeImage);

Parameters

sizeButton
[in] The size of toolbar buttons, in pixels.

sizeImage
[in] The size of toolbar button images, in pixels.

Remarks

The default size of toolbar buttons is 23x22 pixels. The default size of toolbar button images is 16x15 pixels.

Call the CMFCToolBar::GetImageSize method to retrieve the size of toolbar button images. Call the CMFCToolBar::GetButtonSize method to retrieve the size of toolbar buttons.

`CMFCToolBar::SetToolBarBtnText`

Specifies properties of a button on the toolbar.

void SetToolBarBtnText(
    UINT nBtnIndex,
    LPCTSTR szText=NULL,
    BOOL bShowText=TRUE,
    BOOL bShowImage=TRUE);

Parameters

nBtnIndex
[in] The zero-based index of the toolbar button in the list of toolbar buttons.

szText
[in] Specifies the text label of the toolbar button.

bShowText
[in] If this parameter is TRUE, the framework shows the text label. Otherwise, the framework hides the text label.

bShowImage
[in] If this parameter is TRUE, the framework shows the toolbar button image. Otherwise, the framework hides the toolbar button image.

Remarks

By default, the framework shows the images of toolbar buttons but does not show the text label of toolbar buttons.

In Debug builds, this method generates an assertion failure if nBtnIndex does not refer to a valid toolbar button or the toolbar button is a separator.

`CMFCToolBar::SetTwoRowsWithSibling`

Positions the toolbar and its sibling on separate rows.

void SetTwoRowsWithSibling();

Remarks

The framework calls this method when the user selects the Show Buttons on Two Rows button.

Call the CMFCToolBar::SetSiblingToolBar method to enable the Show Buttons on One Row or Show Buttons on Two Rows buttons. If you call CMFCToolBar::SetSiblingToolBar for this toolbar, the sibling toolbar is moved to a separate row. Otherwise, this toolbar is moved to a separate row.

The framework calls the CMFCToolBar::SetOneRowWithSibling method when the user selects the Show Buttons on One Row button.

`CMFCToolBar::SetUserImages`

Sets the collection of user-defined images in the application.

static BOOL SetUserImages(CMFCToolBarImages* pUserImages);

Parameters

pUserImages
[in] A pointer to the collection of user-defined images.

Return Value

Nonzero if the method succeeds; otherwise 0 if the specified CMFCToolBarImages object is not valid or has an image size that differs from the default image size of the toolbar.

Remarks

The framework uses user-defined images to draw toolbar buttons that are customized by the user. The image list specified by pUserImages is shared among all toolbars in the application.

This method generates an assertion failure in Debug builds if the specified CMFCToolBarImages object is not valid or has an image size that differs from the default image size of the toolbar.

The OutlookDemo, ToolTipDemo, and VisualStudioDemo samples use this method to set the global collection of user-defined images. They load the file that is named UserImages.bmp, which is located in the working directory of the application.

Call the `CMFCToolBar::GetUserImages method to retrieve the collection of user-defined images in the application.

`CMFCToolBar::StretchPane`

Stretches the toolbar vertically or horizontally, and repositions the buttons if necessary.

virtual CSize StretchPane(
    int nLength,
    BOOL bVert);

Parameters

nLength
[in] The amount, in pixels, by which to stretch the pane.

bVert
[in] If TRUE, stretches the pane vertically. If FALSE, stretches the pane horizontally.

Return Value

A CSize object that specifies the size of the toolbar client area.

Remarks

This method calls CMFCToolBar::WrapToolBar to reposition the buttons within the stretched toolbar.

The return value is determined by calling CMFCToolBar::CalcSize.

`CMFCToolBar::TranslateChar`

Executes a button command if the specified key code corresponds to a valid keyboard shortcut.

virtual BOOL TranslateChar(UINT nChar);

Parameters

nChar
[in] Specifies a virtual key code. For a list of standard virtual key codes, see Winuser.h

Return Value

FALSE if the specified key code is either unprintable or does not correspond to a valid keyboard shortcut; TRUE if the specified key code corresponds to a drop-down menu option; otherwise, the return value from CMFCToolBar::ProcessCommand.

Remarks

The framework calls this method when a key is pressed together with the Alt key.

`CMFCToolBar::UpdateButton`

Updates the state of the specified button.

void UpdateButton(int nIndex);

Parameters

nIndex
[in] Specifies the zero-based index of the button to update.

Remarks

`CMFCToolBar::WrapToolBar`

Repositions toolbar buttons within the given dimensions.

int WrapToolBar(
    int nWidth,
    int nHeight = 32767,
    CDC* pDC = NULL,
    int nColumnWidth = -1,
    int nRowHeight = -1);

Parameters

nWidth
[in] Maximum width of the toolbar.

nHeight
[in] Maximum height of the toolbar. Not used if the toolbar is floating.

pDC
[in] Pointer to a device context. If NULL, the device context for the toolbar is used.

nColumnWidth
[in] Button width. If -1, the current width is used.

[in] m nRowHeight Button height. If -1, the current height is used.

Return Value

The number of rows of buttons on the toolbar.

Remarks

This method repositions buttons within the toolbar, wrapping buttons to additional rows if necessary.

`CMFCToolBar::m_bDontScaleImages`

Specifies whether or not to scale toolbar images in high DPI mode. Set to TRUE to prevent image scaling when an image size doesn't match a button size.

AFX_IMPORT_DATA static BOOL m_bDontScaleImages;

Share via

CMFCToolBar Class

Syntax

Members

Public Constructors

Public Methods

Protected Methods

Data Members

Remarks

Example

Requirements

Inheritance Hierarchy

CMFCToolBar::AddBasicCommand

Parameters

Remarks

CMFCToolBar::AddCommandUsage

Parameters

Remarks

CMFCToolBar::AddToolBarForImageCollection

Parameters

Return Value

Remarks

CMFCToolBar::AdjustLayout

Remarks

CMFCToolBar::AdjustSize

Remarks

CMFCToolBar::AllowChangeTextLabels

Return Value

Remarks

CMFCToolBar::AllowShowOnList

Return Value

Remarks

CMFCToolBar::AreTextLabels

Return Value

Remarks

CMFCToolBar::AutoGrayInactiveImages

Parameters

Remarks

CMFCToolBar::ButtonToIndex

Parameters

Return Value

CMFCToolBar::CalcFixedLayout

Parameters

Return Value

Remarks

CMFCToolBar::CalcMaxButtonHeight

Return Value

Remarks

CMFCToolBar::CalcSize

Parameters

Return Value

Remarks

CMFCToolBar::CanBeClosed

Return Value

Remarks

CMFCToolBar::CanBeRestored

Return Value

Remarks

CMFCToolBar::CanFocus

Return Value

Remarks

CMFCToolBar::CanHandleSiblings

Return Value

Remarks

CMFCToolBar::CleanUpImages

Remarks

CMFCToolBar::CleanUpLockedImages

Remarks

CMFCToolBar::CommandToIndex

Parameters

Return Value

Remarks

CMFCToolBar::Create

Parameters

Return Value

Remarks

CMFCToolBar::CreateEx

Parameters

Return Value

Remarks

`CMFCToolBar` Class

`CMFCToolBar::AddBasicCommand`

`CMFCToolBar::AddCommandUsage`

`CMFCToolBar::AddToolBarForImageCollection`

`CMFCToolBar::AdjustLayout`

`CMFCToolBar::AdjustSize`

`CMFCToolBar::AllowChangeTextLabels`

`CMFCToolBar::AllowShowOnList`

`CMFCToolBar::AreTextLabels`

`CMFCToolBar::AutoGrayInactiveImages`

`CMFCToolBar::ButtonToIndex`

`CMFCToolBar::CalcFixedLayout`

`CMFCToolBar::CalcMaxButtonHeight`

`CMFCToolBar::CalcSize`

`CMFCToolBar::CanBeClosed`

`CMFCToolBar::CanBeRestored`

`CMFCToolBar::CanFocus`

`CMFCToolBar::CanHandleSiblings`

`CMFCToolBar::CleanUpImages`

`CMFCToolBar::CleanUpLockedImages`

`CMFCToolBar::CommandToIndex`

`CMFCToolBar::Create`

`CMFCToolBar::CreateEx`

`CMFCToolBar::Deactivate`

`CMFCToolBar::DoPaint`

`CMFCToolBar::DrawButton`

`CMFCToolBar::DrawSeparator`

`CMFCToolBar::EnableCustomizeButton`

`CMFCToolBar::EnableDocking`

`CMFCToolBar::EnableLargeIcons`

`CMFCToolBar::EnableQuickCustomization`

`CMFCToolBar::EnableReflections`

`CMFCToolBar::EnableTextLabels`

`CMFCToolBar::FromHandlePermanent`

`CMFCToolBar::GetAllButtons`

`CMFCToolBar::GetAllToolbars`

`CMFCToolBar::GetBasicCommands`

`CMFCToolBar::GetButton`

`CMFCToolBar::GetButtonInfo`

`CMFCToolBar::GetButtonSize`

`CMFCToolBar::GetButtonStyle`

`CMFCToolBar::GetButtonText`

`CMFCToolBar::GetColdImages`

`CMFCToolBar::GetColumnWidth`

`CMFCToolBar::GetCommandButtons`

`CMFCToolBar::GetCount`