CMFCRibbonGallery Class

 

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

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

Implements Office 2007-style ribbon galleries.

class CMFCRibbonGallery : public CMFCRibbonButton  

Public Constructors

NameDescription
CMFCRibbonGallery::CMFCRibbonGalleryConstructs and initializes a CMFCRibbonGallery object.

Public Methods

NameDescription
CMFCRibbonGallery::AddGroupAdds a new group to the gallery.
CMFCRibbonGallery::AddSubItemAdds a new menu item to the drop-down menu.
CMFCRibbonGallery::ClearClears the content of the gallery.
CMFCRibbonGallery::EnableMenuResizeEnables or disables resizing of the menu panel.
CMFCRibbonGallery::EnableMenuSideBarEnables or disables the side bar to the left of the popup menu.
CMFCRibbonGallery::GetCompactSize(Overrides CMFCRibbonButton::GetCompactSize.)
CMFCRibbonGallery::GetDroppedDown(Overrides CMFCRibbonBaseElement::GetDroppedDown.)
CMFCRibbonGallery::GetGroupNameReturns the name of the group that is located at the specified index.
CMFCRibbonGallery::GetGroupOffset
CMFCRibbonGallery::GetIconsInRowReturns the number of items in a row of the ribbon gallery.
CMFCRibbonGallery::GetItemToolTipReturns the tooltip text that is associated with an item in the gallery.
CMFCRibbonGallery::GetLastSelectedItemReturns the index of the last item in the gallery that the user selected.
CMFCRibbonGallery::GetPaletteIDReturns the command ID of the current gallery.
CMFCRibbonGallery::GetRegularSize(Overrides CMFCRibbonButton::GetRegularSize.)
CMFCRibbonGallery::GetSelectedItem
CMFCRibbonGallery::HasMenu(Overrides CMFCRibbonButton::HasMenu.)
CMFCRibbonGallery::IsButtonModeSpecifies whether the gallery is contained in a gallery button.
CMFCRibbonGallery::IsMenuResizeEnabledSpecifies whether menu resizing is enabled or disabled.
CMFCRibbonGallery::IsMenuResizeVertical
CMFCRibbonGallery::IsMenuSideBarSpecifies 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::RedrawIconsRedraws the gallery.
CMFCRibbonGallery::RemoveItemToolTipsRemoves the tooltips from all items in the gallery.
CMFCRibbonGallery::SelectItem
CMFCRibbonGallery::SetACCData(Overrides CMFCRibbonButton::SetACCData.)
CMFCRibbonGallery::SetButtonModeSpecifies whether to display the ribbon gallery as a drop-down button or as a palette directly on the ribbon.
CMFCRibbonGallery::SetGroupNameSets the name of a group.
CMFCRibbonGallery::SetIconsInRowDefines the number of items per row in the gallery.
CMFCRibbonGallery::SetItemToolTipSets the tooltip text for an item in the gallery.
CMFCRibbonGallery::SetPaletteAttaches a palette to a ribbon gallery.
CMFCRibbonGallery::SetPaletteIDDefines the command ID that is sent in the WM_COMMAND message when a gallery item has been selected.

Protected Methods

NameDescription
CMFCRibbonGallery::OnDrawPaletteIconCalled by the framework when a gallery icon is drawn.

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.

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();

CObject CMFCRibbonBaseElement CMFCRibbonButton

CMFCRibbonGallery

Header: afxRibbonPaletteGallery.h

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.

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.

System_CAPS_ICON_note.jpg 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.

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.

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

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.

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.

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

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

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

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

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

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

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

Returns the command ID of the current palette.

int GetPaletteID() const;  

Return Value

The command ID of the currently selected palette.

Remarks

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

virtual CSize GetRegularSize(CDC* pDC);

Parameters

[in] pDC

Return Value

Remarks

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

int GetSelectedItem() const;  

Return Value

Remarks

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

virtual BOOL HasMenu() const;  

Return Value

Remarks

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

Specifies whether menu resizing is enabled.

BOOL IsMenuResizeEnabled() const;  

Return Value

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

Remarks

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

BOOL IsMenuResizeVertical() const;  

Return Value

Remarks

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

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

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

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.

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

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

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.

Removes the tooltips from all items in the gallery.

void RemoveItemToolTips();

Remarks

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

void SelectItem(int nItemIndex);

Parameters

[in] nItemIndex

Remarks

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.

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

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.

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.

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

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

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.

Hierarchy Chart
Classes
CMFCRibbonButton Class
CMFCRibbonGalleryMenuButton Class

Show: