CMFCToolBar Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CMFCToolBar Class.

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.

class CMFCToolBar : public CMFCBaseToolBar  

Public Constructors

NameDescription
CMFCToolBar::CMFCToolBarDefault constructor.
CMFCToolBar::~CMFCToolBarDestructor.

Public Methods

NameDescription
CMFCToolBar::AddBasicCommandAdds a menu command to the list of commands that are always displayed when a user opens a menu.
CMFCToolBar::AddCommandUsageIncrements by one the counter that is associated with the given command.
CMFCToolBar::AddToolBarForImageCollectionAdds images from the user interface resources to the collection of images in the application.
CMFCToolBar::AdjustLayoutRecalculates the size and position of a toolbar. (Overrides CBasePane::AdjustLayout).
CMFCToolBar::AdjustSizeRecalculates the size of the toolbar.
CMFCToolBar::AllowChangeTextLabelsSpecifies whether text labels can be shown under images on the toolbar buttons.
CMFCToolBar::AreTextLabelsSpecifies whether text labels under images are currently displayed on the toolbar buttons.
CMFCToolBar::AutoGrayInactiveImagesEnable or disables the automatic generation of inactive button images.
CMFCToolBar::ButtonToIndexReturns the index of a specified CMFCToolBarButton Class object in this toolbar.
CMFCToolBar::CalcFixedLayoutCalculates the horizontal size of the toolbar. (Overrides CBasePane::CalcFixedLayout.)
CMFCToolBar::CalcSizeCalled by the framework as part of the layout calculation process. (Overrides CPane::CalcSize.)
CMFCToolBar::CanHandleSiblingsDetermines whether the toolbar and its sibling are positioned on the same pane.
CMFCToolBar::CleanUpImagesFrees the system resources allocated for toolbar images.
CMFCToolBar::CleanUpLockedImagesFrees the system resources allocated for locked toolbar images.
CMFCToolBar::CanBeClosedSpecifies whether a user can close the toolbar. (Overrides CBasePane::CanBeClosed.)
CMFCToolBar::CanBeRestoredDetermines whether the system can restore a toolbar to its original state after customization.
CMFCToolBar::CanFocusSpecifies whether the pane can receive focus. (Overrides CBasePane::CanFocus.)
CMFCToolBar::CanHandleSiblingsDetermines whether the toolbar and its sibling are positioned on the same pane.
CMFCToolBar::CommandToIndexReturns the index of the button in the toolbar with a specified command ID.
CMFCToolBar::CreateCreates a CMFCToolBar object.
CMFCToolBar::CreateExCreates a CMFCToolBar object that uses additional style options, such as large icons.
CMFCToolBar::DeactivateDeactivates the toolbar.
CMFCToolBar::EnableCustomizeButtonEnables or disables the Add or Remove Buttons button that appears on the end of the toolbar.
CMFCToolBar::EnableDockingEnables docking of the pane to the main frame. (Overrides CBasePane::EnableDocking.)
CMFCToolBar::EnableLargeIconsEnables or disables large icons on toolbar buttons.
CMFCToolBar::EnableQuickCustomizationEnables 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::EnableReflectionsEnables or disables command reflection.
CMFCToolBar::EnableTextLabelsEnables or disables text labels under toolbar button images.
CMFCToolBar::FromHandlePermanentRetrieves a pointer to the CMFCToolBar object that contains the given window handle.
CMFCToolBar::GetAllButtonsReturns a read-only list of buttons in a toolbar.
CMFCToolBar::GetAllToolbarsReturns a read-only list of all toolbars in the application.
CMFCToolBar::GetBasicCommandsReturns a read-only list of the basic commands defined in the application.
CMFCToolBar::GetButtonReturns a pointer to the CMFCToolBarButton object that has a specified toolbar button index.
CMFCToolBar::GetButtonInfoReturns the command ID, style, and image index of the button at a specified index.
CMFCToolBar::GetButtonSizeReturns the dimensions of each button on the toolbar.
CMFCToolBar::GetButtonStyleReturns the current style of the toolbar button that is located at the specified index.
CMFCToolBar::GetButtonTextReturns the text label of a button that has a specified index.
CMFCToolBar::GetColdImagesReturns a pointer to the collection of cold toolbar button images in the application.
CMFCToolBar::GetColumnWidthReturns the width of the toolbar buttons.
CMFCToolBar::GetCommandButtonsReturns a list of buttons that have a specified command ID from all toolbars in the application.
CMFCToolBar::GetCountReturns the number of buttons and separators on the toolbar.
CMFCToolBar::GetCustomizeButtonRetrieves a pointer to the CMFCCustomizeButton object that is associated with the toolbar.
CMFCToolBar::GetDefaultImageReturns the index of the default image for a toolbar button with a specified command ID.
CMFCToolBar::GetDisabledImagesReturns a pointer to the collection of images that are used for disabled toolbar buttons in the application.
CMFCToolBar::GetDisabledMenuImagesReturns a pointer to the collection of images that are used for disabled menu buttons in the application.
CMFCToolBar::GetDroppedDownMenuRetrieves a pointer to the menu button object that is currently displaying its sub-menu.
CMFCToolBar::GetGrayDisabledButtonsSpecifies whether the images of disabled buttons are dimmed versions of the regular button images, or taken from the collection of disabled button images.
CMFCToolBar::GetHighlightedButtonReturns a pointer to the toolbar button that is currently highlighted.
CMFCToolBar::GetHotBorderDetermines whether the toolbar buttons are hot-tracked.
CMFCToolBar::GetHotTextColorReturns the text color of the highlighted toolbar buttons.
CMFCToolBar::GetHwndLastFocusReturns a handle to the window that had the input focus just before the toolbar did.
CMFCToolBar::GetIgnoreSetTextSpecifies whether calls to set button labels are ignored.
CMFCToolBar::GetImageSizeReturns the current size of toolbar button images.
CMFCToolBar::GetImagesReturns a pointer to the collection of default button images in the application.
CMFCToolBar::GetImagesOffsetReturns the index offset used to find the toolbar button images for this toolbar in the global list of toolbar button images.
CMFCToolBar::GetInvalidateItemRectRetrieves the region of the client area that must be redrawn for the button at the given index.
CMFCToolBar::GetItemIDReturns the command ID of the toolbar button at a specified index.
CMFCToolBar::GetItemRectReturns the bounding rectangle of the button at a specified index.
CMFCToolBar::GetLargeColdImagesReturns a pointer to the collection of large cold toolbar button images in the application.
CMFCToolBar::GetLargeDisabledImagesReturns a pointer to the collection of large disabled toolbar button images in the application.
CMFCToolBar::GetLargeImagesReturns a pointer to the collection of large toolbar button images in the application.
CMFCToolBar::GetLockedColdImagesReturns a pointer to the collection of locked cold images in the toolbar.
CMFCToolBar::GetLockedDisabledImagesReturns a pointer to the collection of locked disabled images in the toolbar.
CMFCToolBar::GetLockedImagesReturns a pointer to the collection of locked button images in the toolbar.
CMFCToolBar::GetLockedImageSizeReturns the default size of locked toolbar images.
CMFCToolBar::GetLockedMenuImagesReturns a pointer to the collection of locked toolbar menu images in the toolbar.
CMFCToolBar::GetMenuButtonSizeReturns the size of menu buttons in the application.
CMFCToolBar::GetMenuImageSizeReturns the size of menu button images in the application.
CMFCToolBar::GetMenuImagesReturns a pointer to the collection of menu button images in the application.
CMFCToolBar::GetOrigButtonsRetrieves the collection of non-customized buttons of the toolbar.
CMFCToolBar::GetOrigResetButtonsRetrieves the collection of non-customized reset buttons of the toolbar.
CMFCToolBar::GetResourceIDRetrieves the resource ID of the toolbar.
CMFCToolBar::GetRouteCommandsViaFrameDetermines which object, the parent frame or the owner, sends commands to the toolbar.
CMFCToolBar::GetRowHeightReturns the height of toolbar buttons.
CMFCToolBar::GetShowTooltipsSpecifies whether tool tips are displayed for toolbar buttons.
CMFCToolBar::GetSiblingToolBarRetrieves the sibling of the toolbar.
CMFCToolBar::GetUserImagesReturns a pointer to the collection of user-defined toolbar button images in the application.
CMFCToolBar::HitTestReturns the index of the toolbar button that is located at the specified position.
CMFCToolBar::InsertButtonInserts a button into the toolbar.
CMFCToolBar::InsertSeparatorInserts a separator into the toolbar.
CMFCToolBar::InvalidateButtonInvalidates the client area of the toolbar button that exists at the provided index.
CMFCToolBar::IsAddRemoveQuickCustomizeDetermines whether a user can add or remove toolbar buttons by using the Customize menu option.
CMFCToolBar::IsAltCustomizeModeSpecifies whether quick customization is being used to drag a button.
CMFCToolBar::IsAutoGrayInactiveImagesSpecifies whether the automatic generation of inactive (non-highlighted) button images is enabled.
CMFCToolBar::IsBasicCommandDetermines whether a command is on the list of basic commands.
CMFCToolBar::IsButtonExtraSizeAvailableDetermines whether the toolbar can display buttons that have extended borders.
CMFCToolBar::IsButtonHighlightedDetermines whether a button on the toolbar is highlighted.
CMFCToolBar::IsCommandPermittedDetermines whether a command is permitted.
CMFCToolBar::IsCommandRarelyUsedDetermines whether a command is rarely used (see CMFCToolBar::SetCommandUsageOptions).
CMFCToolBar::IsCustomizeModeSpecifies whether the toolbar framework is in customization mode.
CMFCToolBar::IsDragButtonDetermines whether a toolbar button is being dragged.
CMFCToolBar::IsExistCustomizeButtonDetermines whether the toolbar contains the Customize button.
CMFCToolBar::IsFloatingDetermines whether the toolbar is floating.
CMFCToolBar::IsLargeIconsSpecifies whether toolbars in the application currently display large icons.
CMFCToolBar::IsLastCommandFromButtonDetermines whether the most recently executed command was sent from the specified toolbar button.
CMFCToolBar::IsLockedDetermines whether the toolbar is locked.
CMFCToolBar::IsOneRowWithSiblingDetermines whether the toolbar and its sibling toolbar are positioned on the same row.
CMFCToolBar::IsUserDefinedSpecifies whether the toolbar is user-defined.
CMFCToolBar::LoadBitmapLoads toolbar images from application resources.
CMFCToolBar::LoadBitmapExLoads toolbar images from application resources. Includes large images.
CMFCToolBar::LoadParametersLoads global toolbar options from the Windows registry.
CMFCToolBar::LoadStateLoads the toolbar state information from the Windows registry. (Overrides CPane::LoadState.)
CMFCToolBar::LoadToolBarLoads the toolbar from application resources.
CMFCToolBar::LoadToolBarExLoads the toolbar from application resources by using the CMFCToolBarInfo helper class to enable the application to use large images.
CMFCToolBar::OnChangeHotCalled by the framework when a user selects a button on the toolbar.
CMFCToolBar::OnFillBackgroundCalled by the framework from CBasePane::DoPaint to fill the toolbar background.
CMFCToolBar::OnResetRestores the toolbar to its original state.
CMFCToolBar::OnSetAccData(Overrides CBasePane::OnSetAccData.)
CMFCToolBar::OnSetDefaultButtonTextRestores the text of a toolbar button to its default state.
CMFCToolBar::OnUpdateCmdUIUsed internally.
CMFCToolBar::RemoveAllButtonsRemoves all buttons from the toolbar.
CMFCToolBar::RemoveButtonRemoves the button with the specified index from the toolbar.
CMFCToolBar::RemoveStateFromRegistryDeletes the state information for the toolbar from the Windows registry.
CMFCToolBar::ReplaceButtonReplaces a toolbar button with another toolbar button.
CMFCToolBar::ResetAllRestores all toolbars to their original states.
CMFCToolBar::ResetAllImagesClears all toolbar image collections in the application.
CMFCToolBar::RestoreOriginalStateRestores the original state of a toolbar.
CMFCToolBar::SaveStateSaves the state information for the toolbar in the Windows registry. (Overrides CPane::SaveState.)
CMFCToolBar::Serialize(Overrides CBasePane::Serialize.)
CMFCToolBar::SetBasicCommandsSets the list of commands that are always displayed when a user opens a menu.
CMFCToolBar::SetButtonInfoSets the command ID, style, and image ID of a toolbar button.
CMFCToolBar::SetButtonStyleSets the style of the toolbar button at the given index.
CMFCToolBar::SetButtonTextSets the text label of a toolbar button.
CMFCToolBar::SetButtonsSets the buttons for the toolbar.
CMFCToolBar::SetCommandUsageOptionsSpecifies when rarely used commands do not appear in the menu of the application.
CMFCToolBar::SetCustomizeModeEnables or disables customization mode for all toolbars in the application.
CMFCToolBar::SetGrayDisabledButtonsSpecifies whether the disabled buttons on the toolbar are dimmed or if disabled images are used for the disabled buttons.
CMFCToolBar::SetHeightSets the height of the toolbar.
CMFCToolBar::SetHotBorderSpecifies whether toolbar buttons are hot-tracked.
CMFCToolBar::SetHotTextColorSets the text color for hot toolbar buttons.
CMFCToolBar::SetLargeIconsSpecifies whether toolbar buttons display large icons.
CMFCToolBar::SetLockedSizesSets the sizes of locked buttons and locked images on the toolbar.
CMFCToolBar::SetMenuSizesSets the size of toolbar menu buttons and their images.
CMFCToolBar::SetNonPermittedCommandsSets the list of commands that cannot be executed by the user.
CMFCToolBar::SetOneRowWithSiblingPositions the toolbar and its sibling on the same row.
CMFCToolBar::SetPermamentSpecifies whether a user can close the toolbar.
CMFCToolBar::SetRouteCommandsViaFrameSpecifies whether the parent frame or the owner sends commands to the toolbar.
CMFCToolBar::SetShowTooltipsSpecifies whether the framework displays tool tips.
CMFCToolBar::SetSiblingToolBarSpecifies the sibling of the toolbar.
CMFCToolBar::SetSizesSpecifies the sizes of buttons and images on all toolbars.
CMFCToolBar::SetToolBarBtnTextSpecifies properties of a button on the toolbar.
CMFCToolBar::SetTwoRowsWithSiblingPositions the toolbar and its sibling on separate rows.
CMFCToolBar::SetUserImagesSets the collection of user-defined images in the application.
CMFCToolBar::StretchPaneStretches the toolbar vertically or horizontally. (Overrides CBasePane::StretchPane.)
CMFCToolBar::TranslateCharExecutes a button command if the specified key code corresponds to a valid keyboard shortcut.
CMFCToolBar::UpdateButtonUpdates the state of the specified button.
CMFCToolBar::WrapToolBarRepositions toolbar buttons within the given dimensions.

Protected Methods

NameDescription
CMFCToolBar::AllowShowOnListDetermines whether the toolbar is displayed in the list on the Toolbars pane of the Customize dialog box.
CMFCToolBar::CalcMaxButtonHeightCalculates the maximum height of a button in the toolbar.
CMFCToolBar::DoPaintRepaints a toolbar.
CMFCToolBar::DrawButtonRepaints a toolbar button.
CMFCToolBar::DrawSeparatorRepaints a separator on a toolbar.
CMFCToolBar::OnUserToolTipCalled by the framework when the tooltip for a button is about to be displayed.

Data Members

NameDescription
CMFCToolBar::m_bDontScaleImagesSpecifies whether to scale or not toolbar images in high DPI mode.
CMFCToolBar::m_dblLargeImageRatioSpecifies the ratio between the dimension (height or width) of large images and the dimension of regular images.

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

  1. Add a CMFCToolBar object to the main frame window.

  2. 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.

  3. 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]--brokenlink--(../Topic/not%20found.md#walkthrough__putting_controls_on_toolbars).

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

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..."));

Header: afxtoolbar.h

CObject

CCmdTarget

CWnd

CBasePane

CPane

CMFCBaseToolBar

CMFCToolBar

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

[in] uiCmd
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.

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

static void __stdcall AddCommandUsage(UINT uiCommand);

Parameters

[in] uiCommand
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.

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

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

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

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

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

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

[in] uiMenuDisabledResID
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.

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 CMFCToolar.

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.

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.

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.

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.

Enable or disables the automatic generation of inactive button images.

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

Parameters

[in] bEnable
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.

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

[in] bRedrawAllToolbars
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.

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

int ButtonToIndex(const CMFCToolBarButton* pButton) const;  

Parameters

[in] pButton
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.

Calculates the horizontal size of the toolbar.

virtual CSize CalcFixedLayout(
    BOOL bStretch,  
    BOOL bHorz);

Parameters

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

[in] bHorz
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.

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.

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

virtual CSize CalcSize(BOOL bVertDock);

Parameters

[in] bVertDock
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.

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.

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.

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.

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.

Frees the system resources allocated for toolbar images.

static void CMFCToolBar::CleanUpImages();

Remarks

The framework calls this method when an application shuts down.

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.

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

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

Parameters

[in] nIDFind
Specifies the command ID.

[in] iIndexFirst
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.

Creates a CMFCToolBar object.

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

Parameters

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

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

[in] nID
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.

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

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

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

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

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

[in] nID
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
	}

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.

Repaints a toolbar.

virtual void DoPaint(CDC* pDC);

Parameters

[in] pDC
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.

Repaints a toolbar button.

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

Parameters

[in] pDC
A pointer to a device context.

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

[in] pImages
A pointer to the toolbar images.

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

[in] bDrawDisabledImages
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.

Repaints a separator on a toolbar.

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

Parameters

[in] pDC
A pointer to a device context.

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

[in] bHorz
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.

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

[in] bEnable
Enables or disables the Customize button.

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

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

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

[in] bQuickCustomize
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.

Enables docking of the pane to the main frame.

virtual void EnableDocking(DWORD dwAlignment);

Parameters

[in] dwAlignment
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.

Enables or disables large icons on toolbar buttons.

void EnableLargeIcons(BOOL bEnable);

Parameters

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

Remarks

By default, large icons are enabled.

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

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

Enables or disables command reflection.

void EnableReflections(BOOL bEnable = TRUE);

Parameters

[in] bEnable
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.

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 .

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

static CMFCToolBar* __stdcall FromHandlePermanent(HWND hwnd);

Parameters

[in] hwnd
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.

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.

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.

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.

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

CMFCToolBarButton* GetButton(int iIndex) const;  

Parameters

[in] iIndex
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.

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

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

[out] nID
The command ID of a button.

[out] nStyle
The style of the button.

[out] iImage
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.

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.

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

UINT GetButtonStyle(int nIndex) const;  

Parameters

[in] nIndex
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

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

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

Parameters

[in] nIndex
The index of a toolbar button.

[out] rString
The label text of the toolbar button.

Return Value

The label text of the toolbar button.

Remarks

Call CMFCToolBar::SetButtonText or CMFCToolBar::SetToolBarBtnText to set the text label.

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

static CMFCToolBarImages* GetColdImages();

Return Value

A pointer to the collection of cold toolbar button images.

Remarks

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

Returns the width of the toolbar buttons.

virtual int GetColumnWidth() const;  

Return Value

A value that specifies the width of toolbar buttons.

Remarks

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

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

[in] uiCmd
The command ID of the buttons.

[out] listButtons
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.

Returns the number of buttons and separators on the toolbar.

int GetCount() const;  

Return Value

The number of buttons and separators on the toolbar.

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.

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

static int GetDefaultImage(UINT uiID);

Parameters

[in] uiID
Specifies the command ID of the button.

Return Value

The index of the toolbar image in the shared list of images.

Remarks

Use this shared method to retrieve the index of the default image for a toolbar button with the specified command ID. The return value is an index into the shared collection of toolbar button images for all toolbars in the application. Call the CMFCToolBar::GetImages method to obtain a pointer to this collection.

Returns a pointer to the collection of images that are used for disabled toolbar buttons in the application.

static CMFCToolBarImages* __stdcall GetDisabledImages();

Return Value

A pointer to the collection of disabled toolbar button images.

Remarks

Load the disabled toolbar button images by using the CMFCToolBarEditBoxButton Class and CMFCToolBar::LoadBitmap methods.

Returns a pointer to the collection of images that are used for disabled menu buttons in the application.

static CMFCToolBarImages* __stdcall GetDisabledMenuImages();

Return Value

A pointer to the collection of disabled menu images.

Remarks

Load the disabled images by using the CMFCToolBarEditBoxButton Class method.

Retrieves a pointer to the menu button object that is currently displaying its sub-menu.

CMFCToolBarMenuButton* GetDroppedDownMenu(int* pIndex = NULL) const;  

Parameters

[out] pIndex
Receives the index of the button in the collection of toolbar buttons.

Return Value

A pointer to the menu button object that is displaying its sub-menu or NULL if no menu is displaying its sub-menu.

Remarks

If this method returns a non- NULL value and pIndex is not NULL, the value pointed to by pIndex is set to the index of the menu button in the collection of toolbar buttons.

Specifies whether the images of disabled buttons are dimmed versions of the regular button images, or taken from the collection of disabled button images.

BOOL GetGrayDisabledButtons() const;  

Return Value

TRUE to dim the images of disabled buttons; FALSEto obtain images from the collection of disabled images.

Remarks

Use CMFCToolBar::SetGrayDisabledButtons to switch between dimmed images and the images from the collection of disabled images.

Returns a pointer to the toolbar button that is currently highlighted.

CMFCToolBarButton* GetHighlightedButton() const;  

Return Value

A pointer to a toolbar button object; or NULL if no button is highlighted.

Remarks

A toolbar button is highlighted if it has keyboard focus. A toolbar button is also highlighted if the toolbar buttons are hot-tracked in this application (for more information, see CMFCToolBar::GetHotBorder and CMFCToolBar::SetHotBorder) and the mouse is pointing at it when no toolbar button or menu item has keyboard focus.

Determines whether the toolbar buttons are hot-tracked. If a button is hot-tracked, it is highlighted when the mouse moves across it.

BOOL GetHotBorder() const;  

Return Value

TRUE if the toolbar buttons are hot-tracked; otherwise, FALSE.

Remarks

By default, toolbar buttons are hot-tracked.

Returns the text color of the highlighted toolbar buttons.

static COLORREF GetHotTextColor();

Return Value

A COLORREF value that represent the current highlighted text color.

Remarks

Call CMFCToolBar::SetHotTextColor to set a new text color for highlighted toolbar buttons.

Returns a handle to the window that had the input focus just before the toolbar did.

HWND GetHwndLastFocus() const;  

Return Value

A handle to window that is not derived from CMFCBaseToolBar Class, which previously had the input focus; or NULL if there is no such window.

Remarks

When a CMFCToolBar control receives the input focus, it stores a handle to the window that lost the focus so that it can restore it later.

Specifies whether calls to set button labels are ignored.

BOOL GetIgnoreSetText() const;  

Return Value

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

Remarks

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.

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.

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.

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

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

[out] lpRect
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.

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

UINT GetItemID(int nIndex) const;  

Parameters

[in] nIndex
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.

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

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

Parameters

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

[out] lpRect
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);

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.

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.

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.

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.

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.

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 disabled images.

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.

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.

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.

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.

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 menu images.

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.

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.

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.

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.

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 clicks 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.

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.

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.

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.

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.

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.

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.

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

virtual int HitTest(CPoint point);

Parameters

[in] point
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.

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

[in] button
Specifies the button to insert.

[in] iInsertAt
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.

Inserts a separator into the toolbar.

virtual int InsertSeparator(INT_PTR iInsertAt=-1);

Parameters

[in] iInsertAt
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.

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

CMFCToolBarButton* InvalidateButton(int nIndex);

Parameters

[in] nIndex
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.

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

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

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.

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

static BOOL IsBasicCommand(UINT uiCmd);

Parameters

[in] uiCmd
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.

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.

Determines whether the specified button is highlighted.

BOOL IsButtonHighlighted(int iButton) const;  

Parameters

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

Return Value

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

Remarks

Determines whether a command is permitted.

static BOOL IsCommandPermitted(UINT uiCmd);

Parameters

[in] uiCmd
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.

Determines whether a command is rarely used.

static BOOL IsCommandRarelyUsed(UINT uiCmd);

Parameters

[in] uiCmd
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.

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).

Determines whether a toolbar button is being dragged.

BOOL IsDragButton(const CMFCToolBarButton* pButton) const;  

Parameters

[in] pButton
Pointer to a toolbar button.

Return Value

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

Remarks

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.

Determines whether the toolbar is floating.

virtual BOOL IsFloating() const;  

Return Value

TRUE if the toolbar is floating; otherwise, FALSE.

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.

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

static BOOL IsLastCommandFromButton(CMFCToolBarButton* pButton);

Parameters

[in] pButton
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.

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.

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.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

virtual BOOL IsResourceChanged() const;  

Return Value

Remarks

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

BOOL IsSibling();

Return Value

Remarks

Specifies whether the toolbar is user-defined.

BOOL IsUserDefined() const;  

Return Value

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

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

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

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

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

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

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

[in] uiMenuDisabledResID
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.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

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

Parameters

[in] params
[in] bLocked

Return Value

Remarks

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

static BOOL __stdcall LoadLargeIconsState(LPCTSTR lpszProfileName = NULL);

Parameters

[in] lpszProfileName

Return Value

Remarks

Loads global toolbar options from the Windows registry.

static BOOL LoadParameters(LPCTSTR lpszProfileName=NULL);

Parameters

[in] lpszProfileName
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.

Loads the toolbar state information from the Windows registry.

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

Parameters

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

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

[in] uiID
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.

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

[in] uiResID
The resource ID of the toolbar.

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

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

[in] bLocked
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.

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

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

[in] uiHotResID
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
	}

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

[in] uiToolbarResID
The resource ID of the toolbar.

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

[in] bLocked
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.

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.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

virtual BOOL NextMenu();

Return Value

Remarks

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

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

Parameters

[in] pButton
Unused.

[in] dropEffect
Unused.

Return Value

Remarks

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

virtual void OnChangeHot(int iHot);

Parameters

[in] iHot
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.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

virtual void OnChangeVisualManager();

Remarks

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

virtual void OnFillBackground(CDC* pDC);

Parameters

[in] pDC
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.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

virtual void OnGlobalFontsChanged();

Remarks

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.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

virtual BOOL OnSetAccData(long lVal);

Parameters

[in] lVal

Return Value

Remarks

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

virtual BOOL OnSetDefaultButtonText(CMFCToolBarButton* pButton);

Parameters

[in] pButton
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.

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

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

Parameters

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

[out] strTTText
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 which 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.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

virtual BOOL PrevMenu();

Return Value

Remarks

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

BOOL ProcessCommand(CMFCToolBarButton* pButton);

Parameters

[in] pButton
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.

Removes all buttons and separators from the toolbar.

virtual void RemoveAllButtons();

Remarks

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

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

virtual BOOL RemoveButton(int iIndex);

Parameters

[in] iIndex
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.

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

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

[in] nIndex
The control ID of the toolbar.

[in] uiID
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.

Replaces a toolbar button with another toolbar button.

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

Parameters

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

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

[in] bAll
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));

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.

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.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

virtual void ResetImages();

Remarks

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

virtual void RestoreFocus();

Remarks

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.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

static BOOL __stdcall SaveParameters(LPCTSTR lpszProfileName = NULL);

Parameters

[in] lpszProfileName

Return Value

Remarks

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

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

[in] nIndex
The control ID of the toolbar.

[in] uiID
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.

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

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

Parameters

[in] lstCommands
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.

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

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

Parameters

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

[in] nID
The command ID of the button.

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

[in] iImage
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.

Sets the buttons for the toolbar.

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

Parameters

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

[in] nIDCount
The number of items in lpIDArray.

[in] bRemapImages
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.

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

virtual void SetButtonStyle(
    int nIndex,  
    UINT nStyle);

Parameters

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

[in] nStyle
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 click a disabled button.

Sets the text label of a toolbar button.

BOOL SetButtonText(
    int nIndex,  
    LPCTSTR lpszText);

Parameters

[in] nIndex
The index of the toolbar button.

[in] lpszText
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.

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

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

Parameters

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

[in] nMinUsagePercentage
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.

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

static BOOL __stdcall SetCustomizeMode(BOOL bSet=TRUE);

Parameters

[in] bSet
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,

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

void SetGrayDisabledButtons(BOOL bGrayDisabledButtons);

Parameters

[in] bGrayDisabledButtons
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.

Sets the height of the toolbar.

void SetHeight(int cyHeight);

Parameters

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

Remarks

This method redraws the toolbar after it sets the height.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

static void __stdcall SetHelpMode(BOOL bOn = TRUE);

Parameters

[in] bOn

Remarks

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

BOOL SetHot(CMFCToolBarButton* pMenuButton);

Parameters

[in] pMenuButton

Return Value

Remarks

Specifies whether toolbar buttons are hot-tracked.

void SetHotBorder(BOOL bShowHotBorder);

Parameters

[in] bShowHotBorder
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.

Sets the text color for hot toolbar buttons.

static void SetHotTextColor(COLORREF clrText);

Parameters

[in] clrText
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.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

void SetIgnoreSetText(BOOL bValue);

Parameters

[in] bValue

Remarks

Specifies whether toolbar buttons display large icons.

static void SetLargeIcons(BOOL bLargeIcons=TRUE);

Parameters

[in] bLargeIcons
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.

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

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

Parameters

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

[in] sizeImage
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.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

void SetMaskMode(BOOL bMasked);

Parameters

[in] bMasked

Remarks

Sets the size of toolbar menu buttons and their images.

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

Parameters

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

[in] sizeImage
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.

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

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

Parameters

[in] lstCommands
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.

Positions the toolbar and its sibling on the same row.

void SetOneRowWithSibling();

Remarks

The framework calls this method when the user clicks 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 clicks the Show Buttons on Two Rows button.

This topic is included for completeness. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

void SetOrigButtons(const CObList& lstOrigButtons);

Parameters

[in] lstOrigButtons

Remarks

Specifies whether a user can close the toolbar.

void SetPermament(BOOL bPermament=TRUE);

Parameters

[in] bPermament
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.

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

void SetRouteCommandsViaFrame(BOOL bValue);

Parameters

[in] bValue
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.

Specifies whether the framework displays tool tips.

static void SetShowTooltips(BOOL bValue);

Parameters

[in] bValue
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.

Specifies the sibling of the toolbar.

void SetSiblingToolBar(CMFCToolBar* pBrotherToolbar);

Parameters

[in] pBrotherToolbar
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.

Specifies the sizes of buttons and images on all toolbars.

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

Parameters

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

[in] sizeImage
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.

Specifies properties of a button on the toolbar.

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

Parameters

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

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

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

[in] bShowImage
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.

Positions the toolbar and its sibling on separate rows.

void SetTwoRowsWithSibling();

Remarks

The framework calls this method when the user clicks 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 clicks the Show Buttons on One Row button.

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

static BOOL SetUserImages(CMFCToolBarImages* pUserImages);

Parameters

[in] pUserImages
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.

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

virtual CSize StretchPane(
    int nLength,  
    BOOL bVert);

Parameters

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

[in] bVert
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.

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

virtual BOOL TranslateChar(UINT nChar);

Parameters

[in] nChar
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.

Updates the state of the specified button.

void UpdateButton(int nIndex);

Parameters

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

Remarks

Repositions toolbar buttons within the given dimensions.

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

Parameters

[in] nWidth
Maximum width of the toolbar.

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

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

[in] nColumnWidth
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.

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

AFX_IMPORT_DATA static BOOL m_bDontScaleImages;  

Remarks

Hierarchy Chart
Classes
CMFCMenuBar Class
CMFCPopupMenuBar Class
CMFCDropDownToolBar Class
Walkthrough: Putting Controls On Toolbars

Show: