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.

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

Syntax

class CMFCToolBar : public CMFCBaseToolBar

Members

Public Constructors

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

Public Methods

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

Protected Methods

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

Data Members

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

Remarks

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

  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.

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

Example

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

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

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

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

Requirements

Header: afxtoolbar.h

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CBasePane

CPane

CMFCBaseToolBar

CMFCToolBar

CMFCToolBar::AddBasicCommand

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

static void __stdcall AddBasicCommand(UINT uiCmd);

Parameters

uiCmd
[in] Specifies the command to add.

Remarks

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

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

CMFCToolBar::AddCommandUsage

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

static void __stdcall AddCommandUsage(UINT uiCommand);

Parameters

uiCommand
[in] Specifies the command counter to increment.

Remarks

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

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

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

CMFCToolBar::AddToolBarForImageCollection

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

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

Parameters

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

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

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

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

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

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

Return Value

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

Remarks

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

CMFCToolBar::AdjustLayout

Recalculates the size and position of a toolbar.

virtual void AdjustLayout();

Remarks

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

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

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

CMFCToolBar::AdjustSize

Recalculates the size of the toolbar.

void AdjustSize();

Remarks

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

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

CMFCToolBar::AllowChangeTextLabels

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

virtual BOOL AllowChangeTextLabels() const;

Return Value

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

Remarks

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

The default implementation returns TRUE.

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

CMFCToolBar::AllowShowOnList

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

virtual BOOL AllowShowOnList() const;

Return Value

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

Remarks

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

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

CMFCToolBar::AreTextLabels

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

BOOL AreTextLabels() const;

Return Value

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

Remarks

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

CMFCToolBar::AutoGrayInactiveImages

Enable or disables the automatic generation of inactive button images.

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

Parameters

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

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

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

Remarks

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

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

CMFCToolBar::ButtonToIndex

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

int ButtonToIndex(const CMFCToolBarButton* pButton) const;

Parameters

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

Return Value

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

CMFCToolBar::CalcFixedLayout

Calculates the horizontal size of the toolbar.

virtual CSize CalcFixedLayout(
    BOOL bStretch,
    BOOL bHorz);

Parameters

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

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

Return Value

A CSize object that specifies the size of the toolbar.

Remarks

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

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

CMFCToolBar::CalcMaxButtonHeight

Calculates the maximum height of buttons in the toolbar.

virtual int CalcMaxButtonHeight();

Return Value

The maximum height of buttons.

Remarks

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

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

CMFCToolBar::CalcSize

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

virtual CSize CalcSize(BOOL bVertDock);

Parameters

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

Return Value

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

Remarks

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

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

CMFCToolBar::CanBeClosed

Specifies whether a user can close the toolbar.

virtual BOOL CanBeClosed() const;

Return Value

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

Remarks

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

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

CMFCToolBar::CanBeRestored

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

virtual BOOL CanBeRestored() const;

Return Value

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

Remarks

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

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

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

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

CMFCToolBar::CanFocus

Specifies whether the pane can receive focus.

virtual BOOL CanFocus() const;

Return Value

This method returns FALSE.

Remarks

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

CMFCToolBar::CanHandleSiblings

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

BOOL CanHandleSiblings();

Return Value

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

Remarks

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

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

CMFCToolBar::CleanUpImages

Frees the system resources allocated for toolbar images.

static void CMFCToolBar::CleanUpImages();

Remarks

The framework calls this method when an application shuts down.

CMFCToolBar::CleanUpLockedImages

Frees the system resources allocated for locked toolbar images.

void CleanUpLockedImages();

Remarks

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

CMFCToolBar::CommandToIndex

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

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

Parameters

nIDFind
[in] Specifies the command ID.

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

Return Value

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

Remarks

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

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

CMFCToolBar::Create

Creates a CMFCToolBar object.

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

Parameters

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

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

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

Return Value

TRUE if this method succeeds; otherwise FALSE.

Remarks

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

CMFCToolBar::CreateEx

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

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

Parameters

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

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

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

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

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

Return Value

Nonzero if this method succeeds; otherwise 0.

Remarks

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

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

Example

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

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

CMFCToolBar::Deactivate

Deactivates the toolbar.

virtual void Deactivate();

Remarks

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

CMFCToolBar::DoPaint

Repaints a toolbar.

virtual void DoPaint(CDC* pDC);

Parameters

pDC
[in] A pointer to a device context.

Remarks

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

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

CMFCToolBar::DrawButton

Repaints a toolbar button.

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

Parameters

pDC
[in] A pointer to a device context.

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

pImages
[in] A pointer to the toolbar images.

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

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

Return Value

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

Remarks

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

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

CMFCToolBar::DrawSeparator

Repaints a separator on a toolbar.

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

Parameters

pDC
[in] A pointer to a device context.

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

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

Remarks

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

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

CMFCToolBar::EnableCustomizeButton

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

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

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

Parameters

bEnable
[in] Enables or disables the Customize button.

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

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

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

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

Remarks

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

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

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

CMFCToolBar::EnableDocking

Enables docking of the pane to the main frame.

virtual void EnableDocking(DWORD dwAlignment);

Parameters

dwAlignment
[in] Specifies the docking alignment to enable.

Remarks

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

CMFCToolBar::EnableLargeIcons

Enables or disables large icons on toolbar buttons.

void EnableLargeIcons(BOOL bEnable);

Parameters

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

Remarks

By default, large icons are enabled.

CMFCToolBar::EnableQuickCustomization

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

static void EnableQuickCustomization(BOOL bEnable=TRUE);

Parameters

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

CMFCToolBar::EnableReflections

Enables or disables command reflection.

void EnableReflections(BOOL bEnable = TRUE);

Parameters

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

Remarks

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

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

CMFCToolBar::EnableTextLabels

Enables or disables text labels under toolbar button images.

void EnableTextLabels(BOOL bEnable=TRUE);

Parameters

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

Remarks

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

CMFCToolBar::FromHandlePermanent

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

static CMFCToolBar* __stdcall FromHandlePermanent(HWND hwnd);

Parameters

hwnd
[in] The window handle to look for.

Return Value

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

Remarks

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

CMFCToolBar::GetAllButtons

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

const CObList& GetAllButtons() const;

Return Value

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

CMFCToolBar::GetAllToolbars

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

static const CObList& GetAllToolbars();

Return Value

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

CMFCToolBar::GetBasicCommands

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

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

Return Value

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

Remarks

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

CMFCToolBar::GetButton

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

CMFCToolBarButton* GetButton(int iIndex) const;

Parameters

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

Return Value

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

CMFCToolBar::GetButtonInfo

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

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

Parameters

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

nID
[out] The command ID of a button.

nStyle
[out] The style of the button.

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

Remarks

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

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

CMFCToolBar::GetButtonSize

Returns the dimensions of each button on the toolbar.

CSize GetButtonSize() const;

Return Value

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

Remarks

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

CMFCToolBar::GetButtonStyle

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

UINT GetButtonStyle(int nIndex) const;

Parameters

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

Return Value

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

Remarks

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

CMFCToolBar::GetButtonText

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

CString GetButtonText(int nIndex) const;

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

Parameters

nIndex
[in] The index of a toolbar button.

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

CMFCToolBar::GetColdImages

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.

CMFCToolBar::GetColumnWidth

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.

CMFCToolBar::GetCommandButtons

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

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

Parameters

uiCmd
[in] The command ID of the buttons.

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

Return Value

The number of buttons that have the specified command ID.

CMFCToolBar::GetCount

Returns the number of buttons and separators on the toolbar.

int GetCount() const;

Return Value

The number of buttons and separators on the toolbar.

CMFCToolBar::GetCustomizeButton

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

CMFCCustomizeButton* GetCustomizeButton();

Return Value

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

Remarks

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

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

CMFCToolBar::GetDefaultImage

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

static int GetDefaultImage(UINT uiID);

Parameters

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

CMFCToolBar::GetDisabledImages

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.

CMFCToolBar::GetDisabledMenuImages

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.

CMFCToolBar::GetDroppedDownMenu

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

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

Parameters

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

CMFCToolBar::GetGrayDisabledButtons

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

BOOL GetGrayDisabledButtons() const;

Return Value

TRUE to dim the images of disabled buttons; FALSE to 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.

CMFCToolBar::GetHighlightedButton

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.

CMFCToolBar::GetHotBorder

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.

CMFCToolBar::GetHotTextColor

Returns the text color of the highlighted toolbar buttons.

static COLORREF GetHotTextColor();

Return Value

A COLORREF value that represents the current highlighted text color.

Remarks

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

CMFCToolBar::GetHwndLastFocus

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.

CMFCToolBar::GetIgnoreSetText

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

CMFCToolBar::GetImages

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

static CMFCToolBarImages* GetImages();

Return Value

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

Remarks

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

CMFCToolBar::GetImageSize

Returns the current size of toolbar button images.

CSize GetImageSize() const;

Return Value

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

CMFCToolBar::GetImagesOffset

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

int GetImagesOffset() const;

Return Value

The index offset of the toolbar images.

Remarks

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

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

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

CMFCToolBar::GetInvalidateItemRect

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

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

Parameters

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

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

Remarks

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

CMFCToolBar::GetItemID

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

UINT GetItemID(int nIndex) const;

Parameters

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

Return Value

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

CMFCToolBar::GetItemRect

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

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

Parameters

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

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

Remarks

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

Example

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

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

CMFCToolBar::GetLargeColdImages

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

static CMFCToolBarImages* GetLargeColdImages();

Return Value

A pointer to the collection of large cold images.

Remarks

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

CMFCToolBar::GetLargeDisabledImages

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

static CMFCToolBarImages* GetLargeDisabledImages();

Return Value

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

Remarks

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

CMFCToolBar::GetLargeImages

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

static CMFCToolBarImages* GetLargeImages();

Return Value

A pointer to the collection of large toolbar button images.

Remarks

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

CMFCToolBar::GetLockedColdImages

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

CMFCToolBarImages* GetLockedColdImages();

Return Value

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

Remarks

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

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

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

CMFCToolBar::GetLockedDisabledImages

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

CMFCToolBarImages* GetLockedDisabledImages();

Return Value

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

Remarks

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

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.

CMFCToolBar::GetLockedImages

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

CMFCToolBarImages* GetLockedImages();

Return Value

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

Remarks

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

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.

CMFCToolBar::GetLockedImageSize

Returns the default size of locked toolbar images.

CSize GetLockedImageSize() const;

Return Value

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

Remarks

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

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

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

CMFCToolBar::GetLockedMenuImages

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

CMFCToolBarImages* GetLockedMenuImages();

Return Value

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

Remarks

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

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.

CMFCToolBar::GetMenuButtonSize

Returns the size of menu buttons in the application.

static CSize GetMenuButtonSize();

Return Value

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

Remarks

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

Call CMFCToolBar::SetMenuSizes to set this global variable.

CMFCToolBar::GetMenuImages

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

static CMFCToolBarImages* GetMenuImages();

Return Value

A pointer to the collection of menu images.

Remarks

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

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

CMFCToolBar::GetMenuImageSize

Returns the size of menu button images in the application.

static CSize GetMenuImageSize();

Return Value

A CSize object that represents the size of menu images.

Remarks

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

CMFCToolBar::GetOrigButtons

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

const CObList& GetOrigButtons() const;

Return Value

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

Remarks

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

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

CMFCToolBar::GetOrigResetButtons

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

const CObList& GetOrigResetButtons() const;

Return Value

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

Remarks

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

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

CMFCToolBar::GetResourceID

Retrieves the resource ID of the toolbar.

UINT GetResourceID() const;

Return Value

The resource ID of the toolbar.

Remarks

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

CMFCToolBar::GetRouteCommandsViaFrame

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

BOOL GetRouteCommandsViaFrame();

Return Value

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

Remarks

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

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

CMFCToolBar::GetRowHeight

Returns the height of toolbar buttons.

virtual int GetRowHeight() const;

Return Value

The height of toolbar buttons, in pixels.

Remarks

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

CMFCToolBar::GetShowTooltips

Specifies whether tool tips are displayed for toolbar buttons.

static BOOL GetShowTooltips();

Return Value

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

Remarks

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

CMFCToolBar::GetSiblingToolBar

Retrieves the sibling of the toolbar.

CMFCToolBar* GetSiblingToolBar();

Return Value

A pointer to the sibling toolbar.

Remarks

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

CMFCToolBar::GetUserImages

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

static CMFCToolBarImages* GetUserImages();

Return Value

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

Remarks

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

CMFCToolBar::HitTest

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

virtual int HitTest(CPoint point);

Parameters

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

Return Value

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

CMFCToolBar::InsertButton

Inserts a button into the toolbar.

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

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

Parameters

button
[in] Specifies the button to insert.

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

Return Value

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

Remarks

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

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

CMFCToolBar::InsertSeparator

Inserts a separator into the toolbar.

virtual int InsertSeparator(INT_PTR iInsertAt=-1);

Parameters

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

Return Value

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

Remarks

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

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

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

CMFCToolBar::InvalidateButton

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

CMFCToolBarButton* InvalidateButton(int nIndex);

Parameters

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

Return Value

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

Remarks

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

CMFCToolBar::IsAddRemoveQuickCustomize

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

BOOL IsAddRemoveQuickCustomize();

Return Value

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

Remarks

CMFCToolBar::IsAltCustomizeMode

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

static BOOL __stdcall IsAltCustomizeMode();

Return Value

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

Remarks

CMFCToolBar::IsAutoGrayInactiveImages

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

static BOOL IsAutoGrayInactiveImages();

Return Value

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

Remarks

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

CMFCToolBar::IsBasicCommand

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

static BOOL IsBasicCommand(UINT uiCmd);

Parameters

uiCmd
[in] Specifies the command to check.

Return Value

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

Remarks

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

CMFCToolBar::IsButtonExtraSizeAvailable

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

virtual BOOL IsButtonExtraSizeAvailable() const;

Return Value

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

Remarks

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

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

CMFCToolBar::IsButtonHighlighted

Determines whether the specified button is highlighted.

BOOL IsButtonHighlighted(int iButton) const;

Parameters

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

Return Value

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

Remarks

CMFCToolBar::IsCommandPermitted

Determines whether a command is permitted.

static BOOL IsCommandPermitted(UINT uiCmd);

Parameters

uiCmd
[in] Specifies the command to check.

Return Value

TRUE if the specified command is permitted; otherwise FALSE.

Remarks

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

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

CMFCToolBar::IsCommandRarelyUsed

Determines whether a command is rarely used.

static BOOL IsCommandRarelyUsed(UINT uiCmd);

Parameters

uiCmd
[in] Specifies the command to check.

Return Value

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

Remarks

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

  • The specified command belongs to the list of basic commands

  • The specified command is one of the standard commands

  • The framework is in customization mode

  • The list of basic commands is empty

  • More than 20% of command calls are calls to the specified command.

CMFCToolBar::IsCustomizeMode

Specifies whether the toolbar framework is in customization mode.

static BOOL IsCustomizeMode();

Return Value

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

Remarks

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

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

CMFCToolBar::IsDragButton

Determines whether a toolbar button is being dragged.

BOOL IsDragButton(const CMFCToolBarButton* pButton) const;

Parameters

pButton
[in] Pointer to a toolbar button.

Return Value

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

Remarks

CMFCToolBar::IsExistCustomizeButton

Determines whether the toolbar contains the Customize button.

BOOL IsExistCustomizeButton();

Return Value

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

Remarks

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

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

CMFCToolBar::IsFloating

Determines whether the toolbar is floating.

virtual BOOL IsFloating() const;

Return Value

TRUE if the toolbar is floating; otherwise, FALSE.

CMFCToolBar::IsLargeIcons

Specifies whether toolbars in the application currently display large icons.

static BOOL IsLargeIcons();

Return Value

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

Remarks

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

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

CMFCToolBar::IsLastCommandFromButton

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

static BOOL IsLastCommandFromButton(CMFCToolBarButton* pButton);

Parameters

pButton
[in] Pointer to button.

Return Value

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

Remarks

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

CMFCToolBar::IsLocked

Determines whether the toolbar is locked.

BOOL IsLocked() const;

Return Value

TRUE if the toolbar is locked; otherwise, FALSE.

Remarks

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

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

CMFCToolBar::IsOneRowWithSibling

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

BOOL IsOneRowWithSibling();

Return Value

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

Remarks

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

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

CMFCToolBar::IsResourceChanged

virtual BOOL IsResourceChanged() const;

Return Value

Remarks

CMFCToolBar::IsSibling

BOOL IsSibling();

Return Value

Remarks

CMFCToolBar::IsUserDefined

Specifies whether the toolbar is user-defined.

BOOL IsUserDefined() const;

Return Value

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

CMFCToolBar::LoadBitmap

Loads toolbar images from application resources.

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

Parameters

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

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

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

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

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

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

Return Value

Nonzero if the method succeeds; otherwise 0.

Remarks

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

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

CMFCToolBar::LoadBitmapEx

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

Parameters

[in] params
[in] bLocked\

Return Value

Remarks

CMFCToolBar::LoadLargeIconsState

static BOOL __stdcall LoadLargeIconsState(LPCTSTR lpszProfileName = NULL);

Parameters

[in] lpszProfileName\

Return Value

Remarks

CMFCToolBar::LoadParameters

Loads global toolbar options from the Windows registry.

static BOOL LoadParameters(LPCTSTR lpszProfileName=NULL);

Parameters

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

Return Value

Nonzero if the method succeeds; otherwise 0.

Remarks

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

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

CMFCToolBar::LoadState

Loads the toolbar state information from the Windows registry.

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

Parameters

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

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

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

Return Value

Nonzero if the method succeeds; otherwise 0.

Remarks

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

CMFCToolBar::LoadToolBar

Loads the toolbar from application resources.

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

Parameters

uiResID
[in] The resource ID of the toolbar.

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

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

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

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

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

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

Return Value

Nonzero if the method succeeds; otherwise 0.

Remarks

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

Example

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

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

CMFCToolBar::LoadToolBarEx

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

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

Parameters

uiToolbarResID
[in] The resource ID of the toolbar.

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

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

Return Value

Nonzero if the method succeeds; otherwise 0.

Remarks

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

CMFCToolBar::m_dblLargeImageRatio

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

AFX_IMPORT_DATA static double m_dblLargeImageRatio;

Remarks

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

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

CMFCToolBar::NextMenu

virtual BOOL NextMenu();

Return Value

Remarks

CMFCToolBar::OnBeforeRemoveButton

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

Parameters

pButton
[in] Unused.

dropEffect
[in] Unused.

Return Value

Remarks

CMFCToolBar::OnChangeHot

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

virtual void OnChangeHot(int iHot);

Parameters

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

Remarks

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

CMFCToolBar::OnChangeVisualManager

virtual void OnChangeVisualManager();

Remarks

CMFCToolBar::OnFillBackground

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

virtual void OnFillBackground(CDC* pDC);

Parameters

pDC
[in] A pointer to a device context.

Remarks

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

Override this method to draw custom background in derived classes.

CMFCToolBar::OnGlobalFontsChanged

virtual void OnGlobalFontsChanged();

Remarks

CMFCToolBar::OnReset

Restores the toolbar to its original state.

virtual void OnReset();

Remarks

Override this method to handle notification about a toolbar reset.

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

CMFCToolBar::OnSetAccData

virtual BOOL OnSetAccData(long lVal);

Parameters

[in] lVal\

Return Value

Remarks

CMFCToolBar::OnSetDefaultButtonText

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

virtual BOOL OnSetDefaultButtonText(CMFCToolBarButton* pButton);

Parameters

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

Return Value

TRUE ifthe text was successfully restored; otherwise FALSE.

Remarks

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

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

CMFCToolBar::OnUserToolTip

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

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

Parameters

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

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

Return Value

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

Remarks

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

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

CMFCToolBar::PrevMenu

virtual BOOL PrevMenu();

Return Value

Remarks

CMFCToolBar::ProcessCommand

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

BOOL ProcessCommand(CMFCToolBarButton* pButton);

Parameters

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

Return Value

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

Remarks

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

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

CMFCToolBar::RemoveAllButtons

Removes all buttons and separators from the toolbar.

virtual void RemoveAllButtons();

Remarks

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

CMFCToolBar::RemoveButton

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

virtual BOOL RemoveButton(int iIndex);

Parameters

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

Return Value

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

Remarks

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

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

CMFCToolBar::RemoveStateFromRegistry

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

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

Parameters

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

nIndex
[in] The control ID of the toolbar.

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

Return Value

Nonzero if the method succeeds; otherwise 0.

Remarks

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

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

CMFCToolBar::ReplaceButton

Replaces a toolbar button with another toolbar button.

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

Parameters

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

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

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

Return Value

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

Remarks

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

Example

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

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

CMFCToolBar::ResetAll

Restores all toolbars to their original states.

static void __stdcall ResetAll();

Remarks

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

CMFCToolBar::ResetAllImages

Clears all toolbar image collections in the application.

static void __stdcall ResetAllImages();

Remarks

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

CMFCToolBar::ResetImages

virtual void ResetImages();

Remarks

CMFCToolBar::RestoreFocus

virtual void RestoreFocus();

Remarks

CMFCToolBar::RestoreOriginalState

Restores the original state of a toolbar.

virtual BOOL RestoreOriginalState();

Return Value

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

Remarks

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

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

CMFCToolBar::SaveParameters

static BOOL __stdcall SaveParameters(LPCTSTR lpszProfileName = NULL);

Parameters

[in] lpszProfileName\

Return Value

Remarks

CMFCToolBar::SaveState

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

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

Parameters

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

nIndex
[in] The control ID of the toolbar.

uiID
[in] The resource ID of the toolbar.

Return Value

Nonzero if the method succeeds; otherwise 0.

Remarks

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

CMFCToolBar::SetBasicCommands

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

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

Parameters

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

Remarks

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

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

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

CMFCToolBar::SetButtonInfo

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

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

Parameters

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

nID
[in] The command ID of the button.

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

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

Remarks

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

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

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

CMFCToolBar::SetButtons

Sets the buttons for the toolbar.

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

Parameters

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

nIDCount
[in] The number of items in lpIDArray.

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

Return Value

Nonzero if the method succeeds; otherwise 0.

Remarks

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

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

CMFCToolBar::SetButtonStyle

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

virtual void SetButtonStyle(
    int nIndex,
    UINT nStyle);

Parameters

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

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

Remarks

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

CMFCToolBar::SetButtonText

Sets the text label of a toolbar button.

BOOL SetButtonText(
    int nIndex,
    LPCTSTR lpszText);

Parameters

nIndex
[in] The index of the toolbar button.

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

Return Value

TRUE if the method succeeds; otherwise FALSE.

Remarks

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

CMFCToolBar::SetCommandUsageOptions

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

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

Parameters

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

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

Return Value

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

Remarks

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

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

CMFCToolBar::SetCustomizeMode

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

static BOOL __stdcall SetCustomizeMode(BOOL bSet=TRUE);

Parameters

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

Return Value

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

Remarks

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

CMFCToolBar::SetGrayDisabledButtons

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

void SetGrayDisabledButtons(BOOL bGrayDisabledButtons);

Parameters

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

Remarks

By default, unavailable buttons are dimmed.

CMFCToolBar::SetHeight

Sets the height of the toolbar.

void SetHeight(int cyHeight);

Parameters

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

Remarks

This method redraws the toolbar after it sets the height.

CMFCToolBar::SetHelpMode

static void __stdcall SetHelpMode(BOOL bOn = TRUE);

Parameters

[in] bOn\

Remarks

CMFCToolBar::SetHot

BOOL SetHot(CMFCToolBarButton* pMenuButton);

Parameters

[in] pMenuButton\

Return Value

Remarks

CMFCToolBar::SetHotBorder

Specifies whether toolbar buttons are hot-tracked.

void SetHotBorder(BOOL bShowHotBorder);

Parameters

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

Remarks

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

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

CMFCToolBar::SetHotTextColor

Sets the text color for hot toolbar buttons.

static void SetHotTextColor(COLORREF clrText);

Parameters

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

Remarks

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

CMFCToolBar::SetIgnoreSetText

void SetIgnoreSetText(BOOL bValue);

Parameters

[in] bValue\

Remarks

CMFCToolBar::SetLargeIcons

Specifies whether toolbar buttons display large icons.

static void SetLargeIcons(BOOL bLargeIcons=TRUE);

Parameters

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

Remarks

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

By default, the framework displays regular icons.

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

CMFCToolBar::SetLockedSizes

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

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

Parameters

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

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

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

Remarks

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

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

CMFCToolBar::SetMaskMode

void SetMaskMode(BOOL bMasked);

Parameters

[in] bMasked\

Remarks

CMFCToolBar::SetMenuSizes

Sets the size of toolbar menu buttons and their images.

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

Parameters

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

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

Remarks

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

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

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

CMFCToolBar::SetNonPermittedCommands

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

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

Parameters

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

Remarks

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

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

CMFCToolBar::SetOneRowWithSibling

Positions the toolbar and its sibling on the same row.

void SetOneRowWithSibling();

Remarks

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

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

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

CMFCToolBar::SetOrigButtons

void SetOrigButtons(const CObList& lstOrigButtons);

Parameters

[in] lstOrigButtons\

Remarks

CMFCToolBar::SetPermament

Specifies whether a user can close the toolbar.

void SetPermament(BOOL bPermament=TRUE);

Parameters

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

Remarks

By default, a user can close each toolbar.

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

CMFCToolBar::SetRouteCommandsViaFrame

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

void SetRouteCommandsViaFrame(BOOL bValue);

Parameters

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

Remarks

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

CMFCToolBar::SetShowTooltips

Specifies whether the framework displays tool tips.

static void SetShowTooltips(BOOL bValue);

Parameters

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

Remarks

By default, the framework shows tool tips.

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

CMFCToolBar::SetSiblingToolBar

Specifies the sibling of the toolbar.

void SetSiblingToolBar(CMFCToolBar* pBrotherToolbar);

Parameters

pBrotherToolbar
[in] A pointer to the sibling toolbar.

Remarks

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

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

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

CMFCToolBar::SetSizes

Specifies the sizes of buttons and images on all toolbars.

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

Parameters

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

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

Remarks

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

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

CMFCToolBar::SetToolBarBtnText

Specifies properties of a button on the toolbar.

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

Parameters

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

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

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

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

Remarks

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

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

CMFCToolBar::SetTwoRowsWithSibling

Positions the toolbar and its sibling on separate rows.

void SetTwoRowsWithSibling();

Remarks

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

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

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

CMFCToolBar::SetUserImages

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

static BOOL SetUserImages(CMFCToolBarImages* pUserImages);

Parameters

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

Return Value

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

Remarks

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

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

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

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

CMFCToolBar::StretchPane

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

virtual CSize StretchPane(
    int nLength,
    BOOL bVert);

Parameters

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

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

Return Value

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

Remarks

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

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

CMFCToolBar::TranslateChar

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

virtual BOOL TranslateChar(UINT nChar);

Parameters

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

Return Value

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

Remarks

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

CMFCToolBar::UpdateButton

Updates the state of the specified button.

void UpdateButton(int nIndex);

Parameters

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

Remarks

CMFCToolBar::WrapToolBar

Repositions toolbar buttons within the given dimensions.

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

Parameters

nWidth
[in] Maximum width of the toolbar.

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

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

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

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

Return Value

The number of rows of buttons on the toolbar.

Remarks

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

CMFCToolBar::m_bDontScaleImages

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

AFX_IMPORT_DATA static BOOL m_bDontScaleImages;

See also

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