CMFCRibbonGallery Class

Implements Office 2007-style ribbon galleries. For more detail see the source code located in the VC\atlmfc\src\mfc folder of your Visual Studio installation.

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

lpszGroupName
[in] Specifies the name of the group.

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

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

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

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

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

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

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

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

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

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

virtual CSize GetCompactSize(CDC* pDC);

Parameters

[in] pDC

Return Value

Remarks

CMFCRibbonGallery::GetDroppedDown

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

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

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

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

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

virtual CSize GetRegularSize(CDC* pDC);

Parameters

[in] pDC

Return Value

Remarks

CMFCRibbonGallery::GetSelectedItem

int GetSelectedItem() const;

Return Value

Remarks

CMFCRibbonGallery::HasMenu

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

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

virtual void OnAfterChangeRect(CDC* pDC);

Parameters

[in] pDC

Remarks

CMFCRibbonGallery::OnDraw

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

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

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

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

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

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

virtual void OnEnable(BOOL bEnable);

Parameters

[in] bEnable

Remarks

CMFCRibbonGallery::OnRTLChanged

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

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

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

data
[out] 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

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

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

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

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

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

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

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

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

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

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

See also

Hierarchy Chart
Classes
CMFCRibbonButton Class
CMFCRibbonGalleryMenuButton Class