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.
class CMFCRibbonGallery : public CMFCRibbonButton
| Name | Description |
|---|---|
| CMFCRibbonGallery::CMFCRibbonGallery | Constructs and initializes a CMFCRibbonGallery object. |
| 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. |
| Name | Description |
|---|---|
| CMFCRibbonGallery::OnDrawPaletteIcon | Called 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);
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.
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);
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.
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.
Clears the content of the gallery.
virtual void Clear();
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);
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.
Enables or disables resizing of the menu panel.
void EnableMenuResize(
BOOL bEnable = TRUE,
BOOL bVertcalOnly = FALSE);
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.
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);
bEnable
[in] TRUE to specify that the side bar is enabled; otherwise, FALSE.
Call this method to enable or disable the Office XP-style side bar at the left side of the menu.
virtual CSize GetCompactSize(CDC* pDC);
[in] pDC
virtual CMFCRibbonBaseElement* GetDroppedDown();
Returns the name of the group that is located at the specified index.
LPCTSTR GetGroupName(int nGroupIndex) const;
nGroupIndex
[in] Specifies the zero-based index for the group whose name you want to retrieve.
The name of the group located at the specified index. Passing an invalid index will result in a failed assertion.
virtual int GetGroupOffset() const;
Returns the number of items in a row of the ribbon gallery.
int GetIconsInRow() const;
The number of items in a row.
Returns the tooltip text that is associated with an item in the gallery.
LPCTSTR GetItemToolTip(int nItemIndex) const;
nItemIndex
[in] Specifies the zero-based index of the item for which to retrieve the tooltip text.
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.
Returns the index of the last item in the ribbon gallery that the user selected.
static int GetLastSelectedItem(UINT uiCmdID);
uiCmdID
[in] Specifies the command ID of the menu item that opened the ribbon gallery.
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.
Returns the command ID of the current palette.
int GetPaletteID() const;
The command ID of the currently selected palette.
virtual CSize GetRegularSize(CDC* pDC);
[in] pDC
int GetSelectedItem() const;
virtual BOOL HasMenu() const;
Specifies whether the palette is contained in a gallery button.
BOOL IsButtonMode() const;
TRUE if the palette is displayed as a drop-down menu button; FALSE if the palette is displayed directly on the ribbon.
Specifies whether menu resizing is enabled.
BOOL IsMenuResizeEnabled() const;
TRUE if menu resizing has been enabled; otherwise, FALSE.
BOOL IsMenuResizeVertical() const;
Specifies whether the side bar is enabled or disabled.
BOOL IsMenuSideBar() const;
TRUE if the Office XP-style side bar is drawn at the left side of the popup menu; otherwise, FALSE.
virtual void OnAfterChangeRect(CDC* pDC);
[in] pDC
virtual void OnDraw(CDC* pDC);
[in] pDC
Called by the framework when a gallery icon is drawn.
virtual void OnDrawPaletteIcon(
CDC* pDC,
CRect rectIcon,
int nIconIndex,
CMFCRibbonGalleryIcon* pIcon,
COLORREF clrText);
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.
You can override this method in a derived class to customize the appearance of a ribbon gallery.
virtual void OnEnable(BOOL bEnable);
[in] bEnable
virtual void OnRTLChanged(BOOL bIsRTL);
[in] bIsRTL
Redraws the gallery.
void RedrawIcons();
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();
void SelectItem(int nItemIndex);
[in] nItemIndex
Populates the specified CAccessibilityData object by using accessibility data from the ribbon gallery.
virtual BOOL SetACCData(
CWnd* pParent,
CAccessibilityData& data);
pParent
[in] The parent window of the ribbon gallery window.
data
[out] A CAccessibilityData object that receives the accessibility data from the ribbon gallery.
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);
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.
Sets the name of a group.
void SetGroupName(
int nGroupIndex,
LPCTSTR lpszGroupName);
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.
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);
nIconsInRow
[in] Specifies the number of items to appear in each row of the gallery.
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);
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.
Attaches a palette to a ribbon gallery.
void SetPalette(CMFCToolBarImages& imagesPalette);
void SetPalette(
UINT uiImagesPaletteResID,
int cxPaletteImage);
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.
Defines the command ID that is sent in the WM_COMMAND message when a user selects a gallery item.
void SetPaletteID(UINT nID);
nID
[in] Specifies the command ID that is sent in the WM_COMMAND message when a user selects a gallery item.
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