CMFCRibbonGallery Class

Article
06/05/2017

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

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

Implements Office 2007-style ribbon galleries.

Syntax

class CMFCRibbonGallery : public CMFCRibbonButton

Members

Public Constructors

Name	Description
CMFCRibbonGallery::CMFCRibbonGallery	Constructs and initializes a `CMFCRibbonGallery` object.

Public Methods

Name	Description
CMFCRibbonGallery::AddGroup	Adds a new group to the gallery.
CMFCRibbonGallery::AddSubItem	Adds a new menu item to the drop-down menu.
CMFCRibbonGallery::Clear	Clears the content of the gallery.
CMFCRibbonGallery::EnableMenuResize	Enables or disables resizing of the menu panel.
CMFCRibbonGallery::EnableMenuSideBar	Enables or disables the side bar to the left of the popup menu.
CMFCRibbonGallery::GetCompactSize	(Overrides CMFCRibbonButton::GetCompactSize.)
CMFCRibbonGallery::GetDroppedDown	(Overrides CMFCRibbonBaseElement::GetDroppedDown.)
CMFCRibbonGallery::GetGroupName	Returns the name of the group that is located at the specified index.
CMFCRibbonGallery::GetGroupOffset
CMFCRibbonGallery::GetIconsInRow	Returns the number of items in a row of the ribbon gallery.
CMFCRibbonGallery::GetItemToolTip	Returns the tooltip text that is associated with an item in the gallery.
CMFCRibbonGallery::GetLastSelectedItem	Returns the index of the last item in the gallery that the user selected.
CMFCRibbonGallery::GetPaletteID	Returns the command ID of the current gallery.
CMFCRibbonGallery::GetRegularSize	(Overrides CMFCRibbonButton::GetRegularSize.)
CMFCRibbonGallery::GetSelectedItem
CMFCRibbonGallery::HasMenu	(Overrides CMFCRibbonButton::HasMenu.)
CMFCRibbonGallery::IsButtonMode	Specifies whether the gallery is contained in a gallery button.
CMFCRibbonGallery::IsMenuResizeEnabled	Specifies whether menu resizing is enabled or disabled.
CMFCRibbonGallery::IsMenuResizeVertical
CMFCRibbonGallery::IsMenuSideBar	Specifies whether the side bar is enabled or disabled.
CMFCRibbonGallery::OnAfterChangeRect	(Overrides `CMFCRibbonButton::OnAfterChangeRect`.)
CMFCRibbonGallery::OnDraw	(Overrides CMFCRibbonButton::OnDraw.)
CMFCRibbonGallery::OnEnable	(Overrides `CMFCRibbonBaseElement::OnEnable`.)
CMFCRibbonGallery::OnRTLChanged	(Overrides CMFCRibbonBaseElement::OnRTLChanged.)
CMFCRibbonGallery::RedrawIcons	Redraws the gallery.
CMFCRibbonGallery::RemoveItemToolTips	Removes the tooltips from all items in the gallery.
CMFCRibbonGallery::SelectItem
CMFCRibbonGallery::SetACCData	(Overrides CMFCRibbonButton::SetACCData.)
CMFCRibbonGallery::SetButtonMode	Specifies whether to display the ribbon gallery as a drop-down button or as a palette directly on the ribbon.
CMFCRibbonGallery::SetGroupName	Sets the name of a group.
CMFCRibbonGallery::SetIconsInRow	Defines the number of items per row in the gallery.
CMFCRibbonGallery::SetItemToolTip	Sets the tooltip text for an item in the gallery.
CMFCRibbonGallery::SetPalette	Attaches a palette to a ribbon gallery.
CMFCRibbonGallery::SetPaletteID	Defines the command ID that is sent in the `WM_COMMAND` message when a gallery item has been selected.

Protected Methods

Name	Description
CMFCRibbonGallery::OnDrawPaletteIcon	Called by the framework when a gallery icon is drawn.

Remarks

A gallery button behaves just like a regular menu button except that it displays a gallery when a user opens it. When you select an item in a gallery, the framework sends the WM_COMMAND message together with command ID of the button. When you handle the message, you should call CMFCRibbonGallery::GetLastSelectedItem to determine which item was selected from the gallery.

Example

The following example demonstrates how to use various methods in the CMFCRibbonGallery class to configure a CMFCRibbonGallery object. The example illustrates how to specify the number of items per row in the gallery, enable resizing of the menu panel, enable the side bar to the left of the pop-up menu, and display the ribbon gallery as a palette directly on the ribbon bar. This code snippet is part of the Draw Client sample.

 CMFCRibbonGallery* pBtnStyles = new CMFCRibbonGallery(ID_OBJECT_STYLES, _T("Styles\nk"), 0, 0, IDB_STYLES, 40);
    pBtnStyles->SetIconsInRow(7);
    pBtnStyles->EnableMenuResize(TRUE, TRUE);
    pBtnStyles->EnableMenuSideBar();
    pBtnStyles->SetButtonMode(false);
    pBtnStyles->RedrawIcons();

Inheritance Hierarchy

CObject CMFCRibbonBaseElement CMFCRibbonButton

CMFCRibbonGallery

Requirements

Header: afxRibbonPaletteGallery.h

CMFCRibbonGallery::AddGroup

Adds a new group to the gallery.

void AddGroup(
    LPCTSTR lpszGroupName,  
    UINT uiImagesPaletteResID,  
    int cxPaletteImage);

 
void AddGroup(
    LPCTSTR lpszGroupName,  
    CMFCToolBarImages& imagesGroup);

 
void AddGroup(
    LPCTSTR lpszGroupName,  
    int nIconsNum);

Parameters

[in] lpszGroupName
Specifies the name of the group.

[in] uiImagesPaletteResID
Specifies the resource ID of the image list that contains the images for the group.

[in] cxPaletteImage
Specifies the width in pixels of an image.

[in] imagesGroup
A reference to image list that contains group images.

[in] nIconsNum
Specifies the number of icons in the group. This parameter should be specified only for custom (owner drawn) groups.

Remarks

You can divide the items on a ribbon gallery into multiple groups by calling this method. Each group can have a caption.

CMFCRibbonGallery::AddSubItem

Adds a new menu item to the drop-down menu.

void AddSubItem(
    CMFCRibbonBaseElement* pSubItem,  
    int nIndex=-1,  
    BOOL bOnTop=FALSE);

Parameters

[in] pSubItem
A pointer to the item to add to the menu.

[in] nIndex
Specifies the zero-based index of a location where to insert the item.

[in] bOnTop
TRUE to specify that the item should be inserted before the ribbon gallery; otherwise, FALSE.

Remarks

You can combine popup galleries with popup menu items by calling this method. Menu items can be placed before or after the gallery.

To insert the item before the gallery, set bOnTop to TRUE. Set bOnTop to FALSE to insert the item below the gallery.

Note

The parameter nIndex specifies the insertion index both at the top of the gallery and at the bottom of the gallery. For example, if you need to insert an item one position before the gallery, set nIndex to 1 and bOnTop to TRUE. Similarly, if you need to insert an item one position below the gallery, set nIndex to 1 and bOnTop to FALSE.

CMFCRibbonGallery::Clear

Clears the content of the gallery.

virtual void Clear();

Remarks

Call this method to remove all content from the ribbon gallery. This must be done before you attach a new ribbon gallery or set of groups to the ribbon gallery.

CMFCRibbonGallery::CMFCRibbonGallery

Constructs and initializes a CMFCRibbonGallery object.

CMFCRibbonGallery (
    UINT nID,  
    LPCTSTR lpszText,  
    int nSmallImageIndex,  
    int nLargeImageIndex,  
    CMFCToolBarImages& imagesPalette);

 
CMFCRibbonGallery (
    UINT nID,  
    LPCTSTR lpszText,  
    int nSmallImageIndex,  
    int nLargeImageIndex,  
    UINT uiImagesPaletteResID=0,  
    int cxPaletteImage=0);

 
CMFCRibbonGallery (
    UINT nID,  
    LPCTSTR lpszText,  
    int nSmallImageIndex,  
    int nLargeImageIndex,  
    CSize sizeIcon,  
    int nIconsNum,  
    BOOL bDefaultButtonStyle=TRUE);

Parameters

nID
Specifies the command ID of the command to execute when a user clicks the button.

lpszText
Specifies the text to appear on the button.

nSmallImageIndex
The zero-based index of the small image to appear on the button.

nLargeImageIndex
The zero-based index of the large image to appear on the button.

imagesPalette
A reference to the CMFCToolBarImages object that contains the images to appear on the gallery.

uiImagesPaletteResID
The resource ID of the list of images to display on the gallery.

cxPaletteImage
Specifies the width, in pixels, of the image on the gallery.

sizeIcon
Specifies the size, in pixels, of the gallery image.

nIconsNum
Specifies the number of icons in the gallery.

bDefaultButtonStyle
Specifies whether to use the default or the owner-drawn button style.

Remarks

CMFCRibbonGallery::EnableMenuResize

Enables or disables resizing of the menu panel.

void EnableMenuResize(
    BOOL bEnable = TRUE,  
    BOOL bVertcalOnly = FALSE);

Parameters

[in] bEnable
TRUE to enable resizing the menu; otherwise, FALSE.

[in] bVertcalOnly
TRUE to specify that the gallery can be resized only vertically; FALSE to specify that the gallery can be resized both vertically and horizontally.

Remarks

Use this method to enable or disable resizing the ribbon gallery. When resizing is enabled, the ribbon gallery displays a gripper that a user can use to resize it.

CMFCRibbonGallery::EnableMenuSideBar

Enables or disables the side bar to the left of the popup menu.

void EnablMenuSideBar(BOOL bEnable=TRUE);

Parameters

[in] bEnable
TRUE to specify that the side bar is enabled; otherwise, FALSE.

Remarks

Call this method to enable or disable the Office XP-style side bar at the left side of the menu.

CMFCRibbonGallery::GetCompactSize

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

virtual CSize GetCompactSize(CDC* pDC);

Parameters

[in] pDC

Return Value

Remarks

CMFCRibbonGallery::GetDroppedDown

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

virtual CMFCRibbonBaseElement* GetDroppedDown();

Return Value

Remarks

CMFCRibbonGallery::GetGroupName

Returns the name of the group that is located at the specified index.

LPCTSTR GetGroupName(int nGroupIndex) const;

Parameters

[in] nGroupIndex
Specifies the zero-based index for the group whose name you want to retrieve.

Return Value

The name of the group located at the specified index. Passing an invalid index will result in a failed assertion.

Remarks

CMFCRibbonGallery::GetGroupOffset

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

virtual int GetGroupOffset() const;

Return Value

Remarks

CMFCRibbonGallery::GetIconsInRow

Returns the number of items in a row of the ribbon gallery.

int GetIconsInRow() const;

Return Value

The number of items in a row.

Remarks

CMFCRibbonGallery::GetItemToolTip

Returns the tooltip text that is associated with an item in the gallery.

LPCTSTR GetItemToolTip(int nItemIndex) const;

Parameters

[in] nItemIndex
Specifies the zero-based index of the item for which to retrieve the tooltip text.

Return Value

A pointer to the tooltip string assigned to an item in the ribbon gallery. It can be NULL if no tooltip is assigned to that item.

Remarks

CMFCRibbonGallery::GetLastSelectedItem

Returns the index of the last item in the ribbon gallery that the user selected.

static int GetLastSelectedItem(UINT uiCmdID);

Parameters

[in] uiCmdID
Specifies the command ID of the menu item that opened the ribbon gallery.

Return Value

When the user selects any item in the ribbon gallery, the library sends the WM_COMMAND message along with Command ID of the menu button that opened the ribbon gallery.

Remarks

CMFCRibbonGallery::GetPaletteID

Returns the command ID of the current palette.

int GetPaletteID() const;

Return Value

The command ID of the currently selected palette.

Remarks

CMFCRibbonGallery::GetRegularSize

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

virtual CSize GetRegularSize(CDC* pDC);

Parameters

[in] pDC

Return Value

Remarks

CMFCRibbonGallery::GetSelectedItem

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

int GetSelectedItem() const;

Return Value

Remarks

CMFCRibbonGallery::HasMenu

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

virtual BOOL HasMenu() const;

Return Value

Remarks

CMFCRibbonGallery::IsButtonMode

Specifies whether the palette is contained in a gallery button.

BOOL IsButtonMode() const;

Return Value

TRUE if the palette is displayed as a drop-down menu button; FALSE if the palette is displayed directly on the ribbon.

Remarks

CMFCRibbonGallery::IsMenuResizeEnabled

Specifies whether menu resizing is enabled.

BOOL IsMenuResizeEnabled() const;

Return Value

TRUE if menu resizing has been enabled; otherwise, FALSE.

Remarks

CMFCRibbonGallery::IsMenuResizeVertical

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

BOOL IsMenuResizeVertical() const;

Return Value

Remarks

CMFCRibbonGallery::IsMenuSideBar

Specifies whether the side bar is enabled or disabled.

BOOL IsMenuSideBar() const;

Return Value

TRUE if the Office XP-style side bar is drawn at the left side of the popup menu; otherwise, FALSE.

Remarks

CMFCRibbonGallery::OnAfterChangeRect

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

virtual void OnAfterChangeRect(CDC* pDC);

Parameters

[in] pDC

Remarks

CMFCRibbonGallery::OnDraw

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

virtual void OnDraw(CDC* pDC);

Parameters

[in] pDC

Remarks

CMFCRibbonGallery::OnDrawPaletteIcon

Called by the framework when a gallery icon is drawn.

virtual void OnDrawPaletteIcon(
    CDC* pDC,  
    CRect rectIcon,  
    int nIconIndex,  
    CMFCRibbonGalleryIcon* pIcon,  
    COLORREF clrText);

Parameters

[in] pDC
A pointer to the device context that is used for drawing.

[in] rectIcon
Specifies the bounding rectangle of the icon to draw.

[in] nIconIndex
Specifies the zero-based index in the image list of gallery icons of the icon to draw.

[in] pIcon
A pointer to the icon being drawn.

[in] clrText
Specifies the color for the text of the item to draw.

Remarks

You can override this method in a derived class to customize the appearance of a ribbon gallery.

CMFCRibbonGallery::OnEnable

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

virtual void OnEnable(BOOL bEnable);

Parameters

[in] bEnable

Remarks

CMFCRibbonGallery::OnRTLChanged

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

virtual void OnRTLChanged(BOOL bIsRTL);

Parameters

[in] bIsRTL

Remarks

CMFCRibbonGallery::RedrawIcons

Redraws the gallery.

void RedrawIcons();

Remarks

Call this function to redraw the gallery. You must call this method if you have changed the contents of the gallery at runtime.

CMFCRibbonGallery::RemoveItemToolTips

Removes the tooltips from all items in the gallery.

void RemoveItemToolTips();

Remarks

CMFCRibbonGallery::SelectItem

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

void SelectItem(int nItemIndex);

Parameters

[in] nItemIndex

Remarks

CMFCRibbonGallery::SetACCData

Populates the specified CAccessibilityData object by using accessibility data from the ribbon gallery.

virtual BOOL SetACCData(
    CWnd* pParent,  
    CAccessibilityData& data);

Parameters

[in] pParent
The parent window of the ribbon gallery window.

[out] data
A CAccessibilityData object that receives the accessibility data from the ribbon gallery.

Return Value

Remarks

TRUE if the method is successful; otherwise, FALSE.

CMFCRibbonGallery::SetButtonMode

Determines whether to display the ribbon gallery as a drop-down button or as a palette directly on the ribbon.

void SetButtonMode(BOOL bSet=TRUE);

Parameters

[in] bSet
TRUE to display the ribbon gallery as a drop-down menu button; FALSE to display the contents of the ribbon gallery directly on the ribbon.

Remarks

CMFCRibbonGallery::SetGroupName

Sets the name of a group.

void SetGroupName(
    int nGroupIndex,  
    LPCTSTR lpszGroupName);

Parameters

[in] nGroupIndex
Specifies the zero-based index for the group for which the name is being changed.

[in] lpszGroupName
Specifies the new name for the group.

Remarks

The group whose name is being changed must have been added using the CMFCRibbonGallery::AddGroup method.

CMFCRibbonGallery::SetIconsInRow

Specifies the number of items per row in the gallery.

void SetIconsInRow(int nIconsInRow);

Parameters

[in] nIconsInRow
Specifies the number of items to appear in each row of the gallery.

Remarks

Use this method to specify the width of the ribbon gallery.

CMFCRibbonGallery::SetItemToolTip

Sets the tooltip text for an item in the gallery.

void SetItemToolTip(
    int nItemIndex,  
    LPCTSTR lpszToolTip);

Parameters

[in] nItemIndex
The zero-based index of the palette item with which to associate the tooltip.

[in] lpszToolTip
The text to appear on the tooltip.

Remarks

CMFCRibbonGallery::SetPalette

Attaches a palette to a ribbon gallery.

void SetPalette(CMFCToolBarImages& imagesPalette);

 
void SetPalette(
    UINT uiImagesPaletteResID,  
    int cxPaletteImage);

Parameters

[in] imagesPalette
Specifies the image list that contains the icons to appear on the gallery.

[in] uiImagesPaletteResID
Specifies the resource ID of the image list that contains the icons to appear on the gallery.

[in] cxPaletteImage
Specifies the width, in pixels, of an image on the gallery.

Remarks

CMFCRibbonGallery::SetPaletteID

Defines the command ID that is sent in the WM_COMMAND message when a user selects a gallery item.

void SetPaletteID(UINT nID);

Parameters

[in] nID
Specifies the command ID that is sent in the WM_COMMAND message when a user selects a gallery item.

Remarks

To determine the specific item that a user selected from the gallery, call the CMFCRibbonGallery::GetLastSelectedItem static method.

Share via

CMFCRibbonGallery Class

Syntax

Members

Public Constructors

Public Methods

Protected Methods

Remarks

Example

Inheritance Hierarchy

Requirements

CMFCRibbonGallery::AddGroup

Parameters

Remarks

CMFCRibbonGallery::AddSubItem

Parameters

Remarks

CMFCRibbonGallery::Clear

Remarks

CMFCRibbonGallery::CMFCRibbonGallery

Parameters

Remarks

CMFCRibbonGallery::EnableMenuResize

Parameters

Remarks

CMFCRibbonGallery::EnableMenuSideBar

Parameters

Remarks

CMFCRibbonGallery::GetCompactSize

Parameters

Return Value

Remarks

CMFCRibbonGallery::GetDroppedDown

Return Value

Remarks

CMFCRibbonGallery::GetGroupName

Parameters

Return Value

Remarks

CMFCRibbonGallery::GetGroupOffset

Return Value

Remarks

CMFCRibbonGallery::GetIconsInRow

Return Value

Remarks

CMFCRibbonGallery::GetItemToolTip

Parameters

Return Value

Remarks

CMFCRibbonGallery::GetLastSelectedItem

Parameters

Return Value

Remarks

CMFCRibbonGallery::GetPaletteID

Return Value

Remarks

CMFCRibbonGallery::GetRegularSize

Parameters

Return Value

Remarks

CMFCRibbonGallery::GetSelectedItem

Return Value

Remarks

CMFCRibbonGallery::HasMenu

Return Value

Remarks

CMFCRibbonGallery::IsButtonMode

Return Value

Remarks

CMFCRibbonGallery::IsMenuResizeEnabled

Return Value

Remarks

CMFCRibbonGallery::IsMenuResizeVertical

Return Value

Remarks

CMFCRibbonGallery::IsMenuSideBar

Return Value

Remarks

CMFCRibbonGallery::OnAfterChangeRect

Parameters