CMFCRibbonBaseElement Class

 

For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.

The CMFCRibbonBaseElement class is the base class for all elements that you can add to a ribbon bar. Examples of ribbon elements are ribbon buttons, ribbon check boxes, and ribbon combo boxes.

class CMFCRibbonBaseElement : public CObject  

Public Constructors

NameDescription
CMFCRibbonBaseElementConstructs a CMFCRibbonBaseElement object.

Public Methods

NameDescription
CMFCRibbonBaseElement::AddToKeyListAdds a keytip for the ribbon element to an array of keytips.
CMFCRibbonBaseElement::AddToListBoxAdds a ribbon element to the specified ribbon commands list box.
CMFCRibbonBaseElement::CanBeAddedToQuickAccessToolBarIndicates whether the ribbon element can be added to the quick access toolbar.
CMFCRibbonBaseElement::CanBeCompactedIndicates whether the size of the ribbon element can be compact.
CMFCRibbonBaseElement::CanBeStretchedIndicates whether the height of the ribbon element can increase vertically to the height of a ribbon row.
CMFCRibbonBaseElement::CanBeStretchedHorizontallyIndicates whether the width of the ribbon element can change.
CMFCRibbonBaseElement::CleanUpSizesCleans up the dimension settings for the ribbon element.
CMFCRibbonBaseElement::ClosePopupMenuCloses the popup menu for the ribbon element.
CMFCRibbonBaseElement::CopyFromCopies the state of the specified CMFCRibbonBaseElement to the current object.
CMFCRibbonBaseElement::DestroyCtrlDestroys the ribbon element.
CMFCRibbonBaseElement::DrawImageDraws the image for the ribbon element.
CMFCRibbonBaseElement::FindReturns the specified pointer to the ribbon element if it points to the current object.
CMFCRibbonBaseElement::FindByDataRetrieves a pointer to the ribbon element if it contains the specified data.
CMFCRibbonBaseElement::FindByIDRetrieves a pointer to the ribbon element if that element is identified by the specified command ID.
CMFCRibbonBaseElement::FindByOriginalRetrieves a pointer to the ribbon element if its original ribbon element matches the specified ribbon element.
CMFCRibbonBaseElement::GetCompactSizeReturns the compact size of the ribbon element.
CMFCRibbonBaseElement::GetDataRetrieves the user-defined data associated with the ribbon element.
CMFCRibbonBaseElement::GetDescriptionReturns the description of the ribbon element.
CMFCRibbonBaseElement::GetDroppedDownRetrieves a pointer to the ribbon element if its pop-up menu is dropped down.
CMFCRibbonBaseElement::GetElementsAdds the current ribbon element to the specified array.
CMFCRibbonBaseElement::GetElementsByIDAdds the current ribbon element to the specified array if the current ribbon element contains the specified command ID.
CMFCRibbonBaseElement::GetHighlightedRetrieves a pointer to the ribbon element if it is highlighted.
CMFCRibbonBaseElement::GetIDReturns the command ID of the ribbon element.
CMFCRibbonBaseElement::GetImageSizeReturns the image size of the ribbon element.
CMFCRibbonBaseElement::GetIntermediateSizeReturns the size of the ribbon element in its intermediate state.
CMFCRibbonBaseElement::GetKeysReturns the keytip associated with the ribbon element.
CMFCRibbonBaseElement::GetKeyTipRectRetrieves the keytip boundary rectangle for the ribbon element.
CMFCRibbonBaseElement::GetKeyTipSizeRetrieves the size of the keytip text.
CMFCRibbonBaseElement::GetLocationInGroupIndicates the display location of the ribbon element in a ribbon group.
CMFCRibbonBaseElement::GetMenuKeysReturns the keytips associated with a button.
CMFCRibbonBaseElement::GetNotifyIDRetrieves the notification command ID for the ribbon element.
CMFCRibbonBaseElement::GetOriginalRetrieves the original ribbon element.
CMFCRibbonBaseElement::GetParentCategoryRetrieves the ribbon category for the ribbon element.
CMFCRibbonBaseElement::GetParentPanelRetrieves the ribbon panel that contains the ribbon element.
CMFCRibbonBaseElement::GetParentRibbonBarRetrieves the parent ribbon bar for the ribbon element.
CMFCRibbonBaseElement::GetParentWndRetrieves the parent window for the ribbon element.
CMFCRibbonBaseElement::GetPressedRetrieves a pointer to the ribbon element if the user currently presses it.
CMFCRibbonBaseElement::GetQuickAccessToolBarIDRetrieves the command ID of the ribbon element when it is located in the quick access toolbar.
CMFCRibbonBaseElement::GetRectReturns the bounding rectangle of the ribbon element.
CMFCRibbonBaseElement::GetRegularSizeReturns the regular size of the ribbon element.
CMFCRibbonBaseElement::GetSizeReturns the current size of the ribbon element.
CMFCRibbonBaseElement::GetTextReturns the text associated with the ribbon element.
CMFCRibbonBaseElement::GetToolTipTextReturns tooltip text of the ribbon element.
CMFCRibbonBaseElement::GetTopLevelRibbonBarRetrieves the top level ribbon bar for the ribbon element.
CMFCRibbonBaseElement::HasCompactModeSpecifies whether the ribbon element has a compact mode.
CMFCRibbonBaseElement::HasFocusIndicates whether the parent element has keyboard focus.
CMFCRibbonBaseElement::HasIntermediateModeSpecifies whether the ribbon element has an intermediate mode.
CMFCRibbonBaseElement::HasLargeModeSpecifies whether the ribbon element has a large mode.
CMFCRibbonBaseElement::HasMenuIndicates whether the ribbon element has a menu.
CMFCRibbonBaseElement::HitTestRetrieves a pointer to the ribbon element if the specified point is located in it.
CMFCRibbonBaseElement::IsAlignByColumnIndicates whether the ribbon element is aligned vertically with other ribbon elements.
CMFCRibbonBaseElement::IsAlwaysLargeImageIndicates whether the ribbon element image size is always large.
CMFCRibbonBaseElement::IsAutoRepeatModeIndicates whether the ribbon element is in auto repeat mode.
CMFCRibbonBaseElement::IsCheckedSpecifies whether the ribbon element is checked.
CMFCRibbonBaseElement::IsCompactModeSpecifies whether the ribbon element is in a compact mode.
CMFCRibbonBaseElement::IsDefaultMenuLook
CMFCRibbonBaseElement::IsDisabledSpecifies whether the ribbon element is disabled.
CMFCRibbonBaseElement::IsDroppedDownDetermines whether the ribbon element displays a popup menu and is dropped down.
CMFCRibbonBaseElement::IsFocusedSpecifies whether the ribbon element has the focus.
CMFCRibbonBaseElement::IsGalleryIconIndicates whether the ribbon element is contained in a ribbon gallery.
CMFCRibbonBaseElement::IsHighlightedSpecifies whether ribbon element is highlighted.
CMFCRibbonBaseElement::IsIntermediateModeIndicates whether the current image for the ribbon element is intermediate size.
CMFCRibbonBaseElement::IsLargeModeIndicates whether the current image for the ribbon element is large sized.
CMFCRibbonBaseElement::IsMenuModeIndicates whether the ribbon element is contained in a menu.
CMFCRibbonBaseElement::IsPressedIndicates whether the user has clicked the ribbon element.
CMFCRibbonBaseElement::IsQATModeIndicates whether the ribbon element is contained in the quick access toolbar.
CMFCRibbonBaseElement::IsSeparatorIndicates whether the ribbon element is a display separator.
CMFCRibbonBaseElement::IsShowGroupBorderIndicates whether the ribbon element is contained in a group that displays a common border.
CMFCRibbonBaseElement::IsShowTooltipOnBottomIndicates whether the tooltip is displayed under the ribbon element.
CMFCRibbonBaseElement::IsTabStopIndicates whether the ribbon element can be selected with the keyboard.
CMFCRibbonBaseElement::IsTextAlwaysOnRightIndicates whether the text for the ribbon element is displayed on the right.
CMFCRibbonBaseElement::IsVisibleIndicates whether the ribbon element is currently displayed.
CMFCRibbonBaseElement::IsWholeRowHeightIndicates whether the display heigth of the ribbon element is the same as the display height of the ribbon panel that contains it.
CMFCRibbonBaseElement::NotifyCommandSends a command notification to the parent window of the ribbon element.
CMFCRibbonBaseElement::NotifyHighlightListItemNotifies the parent window of the ribbon bar when a user highlights a ribbon element that is located in a list.
CMFCRibbonBaseElement::OnAddToQAToolbarAdds the ribbon element to the specified quick access toolbar.
CMFCRibbonBaseElement::OnAfterChangeRectUpdates the tooltip for the ribbon element.
CMFCRibbonBaseElement::OnAutoRepeatUpdates the ribbon element in response to sustained user input.
CMFCRibbonBaseElement::OnCalcTextSizeCalculates the size of the text for the ribbon element.
CMFCRibbonBaseElement::OnChangeMenuHighlightCalled by the framework when the highlight changes for a ribbon element that is located in a menu.
CMFCRibbonBaseElement::OnDrawCalled by the framework to draw the ribbon element.
CMFCRibbonBaseElement::OnDrawKeyTipCalled by the framework to draw the keytip for the ribbon element.
CMFCRibbonBaseElement::OnDrawMenuImageCalled by the framework when the menu image for the ribbon element is drawn.
CMFCRibbonBaseElement::OnDrawOnListCalled by the framework to draw the ribbon element in a commands list box.
CMFCRibbonBaseElement::OnKeyCalled by the framework when the user presses a keytip and the ribbon element has the focus.
CMFCRibbonBaseElement::OnMenuKey
CMFCRibbonBaseElement::OnRTLChangedCalled by the framework when the layout changes direction.
CMFCRibbonBaseElement::OnShowCalled by the framework to show or hide the ribbon element.
CMFCRibbonBaseElement::OnShowPopupMenuCalled by the framework when the ribbon element is going to display a popup menu.
CMFCRibbonBaseElement::PostMenuCommand
CMFCRibbonBaseElement::RedrawUpdates the display for the ribbon element.
CMFCRibbonBaseElement::SetACCDataSets the accessibility data for the ribbon element.
CMFCRibbonBaseElement::SetCompactModeSets the display size for the ribbon element.
CMFCRibbonBaseElement::SetDataAssociates a data item with the ribbon element.
CMFCRibbonBaseElement::SetDefaultMenuLook
CMFCRibbonBaseElement::SetDescriptionSets the description for the ribbon element.
CMFCRibbonBaseElement::SetIDSets the command ID of the ribbon element.
CMFCRibbonBaseElement::SetInitialModeSets the initial display size for the ribbon element.
CMFCRibbonBaseElement::SetKeysSets a keytip for the ribbon element.
CMFCRibbonBaseElement::SetOriginalSets the original ribbon element for the ribbon element.
CMFCRibbonBaseElement::SetParentCategorySets the parent category for the ribbon element.
CMFCRibbonBaseElement::SetParentMenuSets the parent menu container for the ribbon element.
CMFCRibbonBaseElement::SetParentRibbonBarSets the parent ribbon bar for the ribbon element.
CMFCRibbonBaseElement::SetRectSets the dimensions fot he display rectangle for the ribbon element.
CMFCRibbonBaseElement::SetTextSets the text for the ribbon element.
CMFCRibbonBaseElement::SetTextAlwaysOnRightSets the text for the ribbon element to display on the right.
CMFCRibbonBaseElement::SetToolTipTextSets the tooltip text for the ribbon element.
CMFCRibbonBaseElement::SetVisibleSets the visibility state of the ribbon element.
CMFCRibbonBaseElement::StretchHorizontallyStretches the width of the ribbon element.
CMFCRibbonBaseElement::StretchToWholeRowChanges the display height of the ribbon element to the specified row height.
CMFCRibbonBaseElement::UpdateTooltipInfoUpdates the tooltip text by using the command resource for the ribbon element.

Protected Methods

NameDescription
CMFCRibbonBaseElement::OnProcessKeyCalled by the framework when the user presses a shortcut key.
CMFCRibbonBaseElement::OnSetFocusCalled by the framework when a ribbon element receives or loses the input focus.

The CMFCRibbonBaseElement class defines the properties that are common to all ribbon elements that include command ID, text label, tooltip text, element description, and state (which can be focused, highlighted, pressed, disabled, checked, or dropped down).

The image size of a ribbon element is defined by the RibbonImageType member, which can be one of the following values:

  • RibbonImageLarge

  • RibbonImageSmall

Depending on its size, a ribbon element displays either a small or large image.

The following example demonstrates how to use various methods in the CMFCRibbonBaseElement class. The example shows how to get a CMFCRibbonBaseElement object from a CMFCRibbonStatusBar class, set the description for the ribbon element, set the text, set a keytip, and set the tooltip text for the ribbon element. This code snippet is part of the Draw Client sample.

	// CMFCRibbonStatusBar m_wndStatusBar
	CMFCRibbonBaseElement* pPane = m_wndStatusBar.FindByID(nID);

		pPane->SetDescription(_T("a pane"));
		// CString strText
		pPane->SetText(strText);
		pPane->SetKeys(_T("p"));
		pPane->SetToolTipText(_T("this is a pane"));

CObject

CMFCRibbonBaseElement

Header: afxbaseribbonelement.h

Adds a keytip for the ribbon element to an array of keytips.

virtual void AddToKeyList(
    CArray<CMFCRibbonKeyTip*, CMFCRibbonKeyTip*>& arElems);

Parameters

[in] arElems
Reference to a CArray of keytips.

Remarks

When the ribbon keytips feature is enabled, the framework displays ribbon keytips when the user presses the ALT key or the F10 key.

Adds a ribbon element to the specified ribbon commands list box.

virtual int AddToListBox(
    CMFCRibbonCommandsListBox* pWndListBox,  
    BOOL bDeep);

Parameters

[in] pWndListBox
Pointer to a commands list box.

[in] bDeep
This parameter is not used.

Return Value

The zero-based index of the added ribbon element.

Remarks

The framework adds ribbon elements to a commands list box to enable the user to customize the user interface.

Indicates whether the ribbon element can be added to the quick access toolbar.

virtual BOOL CanBeAddedToQuickAccessToolBar() const;  

Return Value

TRUE if the element can be added; otherwise, FALSE.

Remarks

Indicates whether the size of the ribbon element can be compact.

virtual BOOL CanBeCompacted() const;  

Return Value

TRUE if the size of the ribbon element can be compact; otherwise, FALSE.

Remarks

The size of a ribbon element can be compact, intermediate, or large.

Indicates whether the height of the ribbon element can increase vertically to the height of a ribbon row.

virtual BOOL CanBeStretched();

Return Value

Always returns TRUE.

Remarks

By default this method always returns TRUE. Override this method to indicate whether the height of the ribbon element can increase vertically to the height of a ribbon row.

Indicates whether the width of the ribbon element can change.

virtual BOOL CanBeStretchedHorizontally();

Return Value

Always returns FALSE.

Remarks

By default this method always returns FALSE. Override this method to indicate whether the width of the ribbon element can change.

Cleans up the dimension settings for the ribbon element.

virtual void CleanUpSizes();

Remarks

By default this method does nothing. Override this method in a derived class to reset the dimension settings for the ribbon element.

Closes the pop-up menu for the ribbon element.

virtual void ClosePopupMenu();

Remarks

Copies the state of the specified CMFCRibbonBaseElement to the current object.

virtual void CopyFrom(const CMFCRibbonBaseElement& src);

Parameters

[in] src
The source CMFCRibbonBaseElement object.

Remarks

Destroys the ribbon element.

virtual void DestroyCtrl();

Remarks

By default this method does nothing. Override this method in a derived class to destroy the ribbon element.

Draws the image for the ribbon element.

virtual void DrawImage(
    CDC* pDC,  
    RibbonImageType type,  
    CRect rectImage);

Parameters

[in] pDC
Pointer to a device context.

[in] type
An image type enumerated value. See the Remarks section for a list of possible values.

[in] rectImage
The image rectangle.

Remarks

By default this method does nothing. Override this method in a derived class to draw the image for the ribbon element.

The following table lists possible values for the type parameter:

RibbonImageLarge
Large 32x32 pixel image size.

RibbonImageSmall
Small 16x16 pixel image size.

Returns the specified pointer if it points to the current object.

virtual CMFCRibbonBaseElement* Find(const CMFCRibbonBaseElement* pElement);

Parameters

[in] pElement
Pointer to a ribbon element.

Return Value

A pointer to the ribbon element if pElement points to the current object; otherwise NULL.

Remarks

Retrieves a pointer to the ribbon element if it contains the specified data.

virtual CMFCRibbonBaseElement* FindByData(DWORD_PTR dwData);

Parameters

[in] dwData
The data associated with a ribbon element.

Return Value

A pointer to the ribbon element if it contains the specified data; otherwise NULL.

Remarks

Retrieves a pointer to the ribbon element if that element is identified by the specified command ID.

virtual CMFCRibbonBaseElement* FindByID(UINT uiCmdID);

Parameters

[in] uiCmdID
Command ID for a ribbon element.

Return Value

A pointer to the ribbon element if that element is identified by the specified command ID; otherwise NULL.

Remarks

Retrieves a pointer to the current ribbon element if its original ribbon element matches the specified ribbon element.

virtual CMFCRibbonBaseElement* FindByOriginal(CMFCRibbonBaseElement* pOriginal);

Parameters

[in] pOriginal
Pointer to a ribbon element.

Return Value

A pointer to the ribbon element if its original ribbon element matches the specified ribbon element; otherwise NULL.

Remarks

Ribbon elements that are copied to another container retain a pointer to the original ribbon element.

Returns the compact size of the ribbon element.

virtual CSize GetCompactSize(CDC* pDC);

Parameters

[in] pDC
A pointer to a device context.

Return Value

The compact size of a ribbon element.

System_CAPS_ICON_note.jpg Note

The compact size means that the ribbon element is truncated (it displays a small image, or an image without a text).

Retrieves the user-defined data associated with the ribbon element.

DWORD_PTR GetData() const;  

Return Value

The user-defined data associated with the ribbon element.

Returns the description of the ribbon element.

virtual CString GetDescription() const;  

Return Value

The ribbon element description. The description is displayed either on the status bar, or in a tooltip, or under the menu button if the ribbon element is located on the CMFCRibbonMainPanel Class.

Retrieves a pointer to the ribbon element if its pop-up menu is dropped down.

virtual CMFCRibbonBaseElement* GetDroppedDown();

Return Value

A pointer to the ribbon element if its pop-up menu is dropped down; otherwise NULL.

Remarks

Adds the current ribbon element to the specified array.

virtual void GetElements(
    CArray<CMFCRibbonBaseElement*, CMFCRibbonBaseElement*>& arElements);

Parameters

[in, out] arElements
An array of ribbon elements.

Remarks

Adds the current ribbon element to the specified array if the current ribbon element contains the specified command ID.

virtual void GetElementsByID(
    UINT uiCmdID,  
    CArray<CMFCRibbonBaseElement*, CMFCRibbonBaseElement*>& arElements);

Parameters

[in] uiCmdID
Command ID of a ribbon element.

[in] arElements
An array of ribbon elements.

Remarks

Retrieves a pointer to the ribbon element if it is highlighted.

virtual CMFCRibbonBaseElement* GetHighlighted();

Return Value

A pointer to the ribbon element if it is highlighted; otherwise NULL.

Remarks

Returns the command ID of the ribbon element.

UINT GetID() const;  

Return Value

The command ID of the ribbon element.

Returns the image size of the ribbon element.

virtual CSize GetImageSize(RibbonImageType R) const;  

Return Value

The image size of the ribbon element.

Returns the size of the ribbon element in its intermediate state.

virtual CSize GetIntermediateSize(CDC* pDC);

Parameters

[in] pDC
A pointer to a device context.

Return Value

The size of the ribbon element in its intermediate state.

Returns the keytip associated with the ribbon element.

LPCTSTR GetKeys() const;  

Return Value

A keytip associated with the ribbon element.

Retrieves the keytip boundary rectangle for the ribbon element.

virtual CRect GetKeyTipRect(
    CDC* pDC,  
    BOOL bIsMenu);

Parameters

[in] pDC
Pointer to a device context.

[in] bIsMenu
TRUE if the ribbon element displays a pop-up menu; otherwise FALSE.

Return Value

Always returns a rectangle with 0 values.

Remarks

Override this method in a derived class to return the keytip boundary rectangle.

Retrieves the size of the keytip text.

virtual CSize GetKeyTipSize(CDC* pDC);

Parameters

[in] pDC
Pointer to a device context.

Return Value

The size of the keytip text.

Remarks

Indicates the display location of the ribbon element in a ribbon group.

RibbonElementLocation GetLocationInGroup() const;  

Return Value

A RibbonElementLocation enumerated value. The following table lists possible values.

ValueDescription
RibbonElementNotInGroupThe ribbon element is not contained in a ribbon group.
RibbonElementSingleInGroupThe ribbon element is displayed as the only item in a ribbon group.
RibbonElementFirstInGroupThe ribbon element is displayed on the left end of a ribbon group.
RibbonElementLastInGroupThe ribbon element is displayed on the right end of a ribbon group.
RibbonElementMiddleInGroupThe ribbon element is not displayed on either end of a ribbon group.

Remarks

Ribbon element groups are only aligned horizontally.

Returns the menu keytip for the ribbon element.

LPCTSTR GetMenuKeys() const;  

Return Value

The menu keytip associated with the ribbon element.

Remarks

When invoked, a menu keytip displays a pop-up menu.

Retrieves the notification command ID for the ribbon element.

virtual UINT GetNotifyID();

Return Value

The notification command ID.

Remarks

Retrieves the original ribbon element.

CMFCRibbonBaseElement* GetOriginal() const;  

Return Value

A pointer to the original ribbon element.

Remarks

Ribbon elements that are copied to another container retain a pointer to the original ribbon element.

Retrieves the ribbon category for the ribbon element.

CMFCRibbonCategory* GetParentCategory() const;  

Return Value

A pointer to the ribbon category.

Remarks

Retrieves the ribbon panel that contains the ribbon element.

virtual CMFCRibbonPanel* GetParentPanel() const;  

Return Value

A pointer to the ribbon panel that contains the ribbon element.

Remarks

Retrieves the parent ribbon bar for the ribbon element.

CMFCRibbonBar* GetParentRibbonBar() const;  

Return Value

A pointer to the parent ribbon bar for the ribbon element.

Remarks

Retrieves the parent window for the ribbon element.

virtual CWnd* GetParentWnd() const;  

Return Value

A pointer to the parent window for the ribbon element if the method was successful; otherwise, NULL.

Remarks

The parent window for a ribbon element is a CMFCRibbonBar Class or a CMFCRibbonPanelMenuBar.

Retrieves a pointer to the ribbon element if the user currently presses it.

virtual CMFCRibbonBaseElement* GetPressed();

Return Value

A pointer to the ribbon element if the user currently presses it; otherwise, NULL.

Remarks

Retrieves the command ID of the ribbon element when it is located in the quick access toolbar.

virtual UINT GetQuickAccessToolBarID() const;  

Return Value

The command ID of the ribbon element when it is located in the quick access toolbar.

Remarks

Returns the bounding rectangle of the ribbon element.

CRect GetRect() const;  

Return Value

The bounding rectangle of the ribbon element. The position of the rectangle is in the coordinates of the parent Ribbon control.

Returns the regular size of the ribbon element.

virtual CSize GetRegularSize(CDC* pDC) = 0;  

Parameters

[in] pDC
A pointer to a device context.

Return Value

The regular size of the ribbon element.

Remarks

System_CAPS_ICON_note.jpg Note

The regular size is the maximal possible size of the ribbon element.

Returns the current size of the ribbon element.

virtual CSize GetSize(CDC* pDC);

Parameters

[in] pDC
A pointer to a device context.

Return Value

The current size of the ribbon element.

Returns the text associated with the ribbon element.

LPCTSTR GetText() const;  

Return Value

The text associated with the ribbon element.

Returns tooltip text of the ribbon element.

virtual CString GetToolTipText() const;  

Return Value

The tooltip text of the ribbon element.

Retrieves the top level ribbon bar for the ribbon element.

CMFCRibbonBar* GetTopLevelRibbonBar() const;  

Return Value

A pointer to the top level ribbon bar for the ribbon element if the method was successful; otherwise, NULL.

Remarks

Specifies whether the ribbon element has a compact mode.

virtual BOOL HasCompactMode() const;  

Return Value

TRUE if the ribbon element has a compact mode. FALSE otherwise.

Remarks

System_CAPS_ICON_note.jpg Note

In the compact mode, an element displays a small image only.

Specifies whether the ribbon element has an intermediate mode.

virtual BOOL HasIntermediateMode() const;  

Return Value

TRUE if the ribbon element has an intermediate mode, FALSE otherwise. In the intermediate mode, an element displays a small image and text on the right of the image.

Remarks

Determines whether the ribbon element has a large mode.

virtual BOOL HasLargeMode() const;  

Return Value

TRUE if the ribbon element has a large mode. FALSE otherwise.

Remarks

In the large mode, an element can take the full height of the parent panel.

Indicates whether the ribbon element has a menu.

virtual BOOL HasMenu() const;  

Return Value

Always returns FALSE.

Remarks

By default this method always returns FALSE. Override this method in a derived class to indicate whether the ribbon element has a menu.

Retrieves a pointer to the ribbon element if the specified point is located in it.

virtual CMFCRibbonBaseElement* HitTest(CPoint point);

Parameters

[in] point
This parameter is not used.

Return Value

A pointer to the ribbon element if it exists; otherwise FALSE.

Remarks

By default this method always returns a valid pointer to the ribbon element when it exists. Override this method to indicate if the point resides in the ribbon element.

Indicates whether the ribbon element is aligned vertically with other ribbon elements.

virtual BOOL IsAlignByColumn() const;  

Return Value

Always returns TRUE.

Remarks

By default this method always returns TRUE. Override this method in a derived class to indicate whether the derived ribbon element is aligned vertically with other ribbon elements.

Indicates whether the ribbon element image size is always large.

virtual BOOL IsAlwaysLargeImage() const;  

Return Value

TRUE if the ribbon element image size is always large; otherwise FALSE.

Remarks

Large image size is 32 x 32 pixels.

Indicates whether the ribbon element is in auto repeat mode.

virtual BOOL IsAutoRepeatMode(int& nDelay) const;  

Parameters

[in] nDelay
This parameter is not used.

Return Value

Always returns FALSE.

Remarks

By default this method always returns FALSE. Override this method to indicate whether the ribbon element is in auto repeat mode.

In auto repeat mode, the ribbon element responds at a set interval, measured in milliseconds, to sustained user input.

Specifies whether the ribbon element is checked.

virtual BOOL IsChecked() const;  

Return Value

TRUE if the ribbon element is checked; otherwise FALSE.

Specifies whether the ribbon element is in a compact mode.

BOOL IsCompactMode() const;  

Return Value

TRUE if the ribbon element is in a compact mode; otherwise FALSE.

Indicates whether the ribbon element is set to appear as a pop-up command.

BOOL IsDefaultMenuLook() const;  

Return Value

TRUE if the ribbon element is set to appear as a pop-up command; otherwise FALSE.

Remarks

Specifies whether the ribbon element is disabled.

virtual BOOL IsDisabled() const;  

Return Value

TRUE if the ribbon element is disabled; otherwise FALSE.

Specifies whether the ribbon element displays a pop-up menu and is dropped down.

virtual BOOL IsDroppedDown() const;  

Return Value

TRUE if the ribbon element is dropped down and displays a pop-up menu; otherwise FALSE.

Specifies whether the ribbon element has the focus.

virtual BOOL IsFocused() const;  

Return Value

TRUE if the ribbon element has the focus; otherwise FALSE.

Indicates whether the ribbon element is contained in a ribbon gallery.

virtual BOOL IsGalleryIcon() const;  

Return Value

Always returns FALSE.

Remarks

By default this method always returns FALSE. Override this method in a derived class to indicate whether the ribbon element is contained in a ribbon gallery.

Specifies whether ribbon element is highlighted.

virtual BOOL IsHighlighted() const;  

Return Value

TRUE if the ribbon element is highlighted; otherwise FALSE.

Remarks

Indicates whether the current image for the ribbon element is intermediate size.

BOOL IsIntermediateMode() const;  

Return Value

TRUE if the image for the ribbon element is intermediate size; otherwise FALSE.

Remarks

Intermediate image size is 16 x 16 pixels.

Indicates whether the current image for the ribbon element is large size.

BOOL IsLargeMode() const;  

Return Value

TRUE if the image for the ribbon element is large size; otherwise FALSE.

Remarks

Large image size is 32 x 32 pixels.

Indicates whether the ribbon element is contained in a menu.

BOOL IsMenuMode() const;  

Return Value

TRUE if the ribbon element is contained in a menu; otherwise, FALSE.

Remarks

Indicates whether the user has clicked the ribbon element.

virtual BOOL IsPressed() const;  

Return Value

TRUE if the user has clicked the ribbon element; otherwise FALSE.

Indicates whether the ribbon element is contained in the quick access toolbar.

BOOL IsQATMode() const;  

Return Value

TRUE if the ribbon element is contained in the quick access toolbar; otherwise, FALSE.

Remarks

Indicates whether the ribbon element is a display separator.

virtual BOOL IsSeparator() const;  

Return Value

TRUE if the ribbon element is a display separator; otherwise FALSE.

Remarks

Indicates whether the ribbon element is contained in a group that displays a common border.

BOOL IsShowGroupBorder() const;  

Return Value

TRUE if the ribbon element is contained in a group that displays a common border; otherwise, FALSE.

Remarks

Indicates whether the tooltip is displayed under the ribbon element.

virtual BOOL IsShowTooltipOnBottom() const;  

Return Value

TRUE if the tooltip is displayed under the ribbon element; FALSE if the tooltip is displayed near the pointer.

Remarks

Indicates whether the ribbon element can be selected with the keyboard.

virtual BOOL IsTabStop() const;  

Return Value

Always returns TRUE.

Remarks

By default this method always returns TRUE. Override this method to indicate whether the ribbon element can be selected with the keyboard.

Indicates whether the text for the ribbon element is displayed on the right.

BOOL IsTextAlwaysOnRight() const;  

Return Value

TRUE if the text for the ribbon element is displayed on the right; otherwise, FALSE.

Remarks

Indicates whether the ribbon element is currently displayed.

BOOL IsVisible() const;  

Return Value

TRUE if the ribbon element is currently displayed; otherwise, FALSE.

Remarks

Indicates whether the display height of the ribbon element is the same as the display height of the ribbon panel that contains it.

virtual BOOL IsWholeRowHeight() const;  

Return Value

Always returns FALSE.

Remarks

By default this method always returns FALSE. Override this method to indicate whether the display height of the ribbon element is the same as the display height of the ribbon panel that contains it.

Sends a command notification to the parent window of the ribbon element.

BOOL NotifyCommand(BOOL bWithDelay = FALSE);

Parameters

[in] bWithDelay
TRUE to add the command notification to the message queue of the parent window; FALSE to send the message immediately to the parent window.

Return Value

TRUE if the message was sent; otherwise, FALSE.

Remarks

Notifies the parent window of the ribbon bar when a user highlights a ribbon element that is located in a list.

virtual void NotifyHighlightListItem(int nIndex);

Parameters

[in] nIndex
The index of the ribbon element in the list.

Remarks

Adds the ribbon element to the specified quick access toolbar.

virtual BOOL OnAddToQAToolbar(CMFCRibbonQuickAccessToolBar& qat);

Parameters

[in] qat
The quick access toolbar.

Return Value

Always returns TRUE indicating the ribbon element was added to the quick access toolbar.

Remarks

Updates the tooltip for the ribbon element.

virtual void OnAfterChangeRect(CDC* pDC);

Parameters

[in] pDC
This parameter is not used.

Remarks

By default this method updates the tooltip for the ribbon element. Override this method to update the ribbon element after its display rectangle has changed.

Updates the ribbon element in response to sustained user input.

virtual BOOL OnAutoRepeat();

Return Value

Always returns FALSE.

Remarks

By default this method always return FALSE. Override this method to process sustained user input.

Calculates the size of the text for the ribbon element.

virtual void OnCalcTextSize(CDC* pDC);

Parameters

[in] pDC
This parameter is not used.

Remarks

By default this method does nothing. Override this method to calculate the size of the text for the ribbon element.

Called by the framework when the highlight changes for a ribbon element that is located in a menu.

virtual void OnChangeMenuHighlight(CMFCRibbonPanelMenuBar* pPanelMenuBar  
    CMFCRibbonBaseElement* pHot);

Parameters

[in] pPanelMenuBar
This parameter is not used.

[in] pHot
This parameter is not used.

Remarks

By default this method does nothing. Override this method to update a ribbon element that is located in a menu when the highlight changes.

Called by the framework to draw the ribbon element.

virtual void OnDraw(CDC* pDC) = 0;  

Parameters

[in] pDC
A pointer to a device context.

Remarks

Override this method in a derived class if you want to customize the drawing of a specific ribbon element.

Called by the framework to draw the keytip for the ribbon element.

virtual void OnDrawKeyTip(
    CDC* pDC,  
    const CRect& rect,  
    BOOL bIsMenu);

Parameters

[in] pDC
Pointer to a device context.

[in] rect
Boundary rectangle for the keytip.

[in] bIsMenu
TRUE if the keytip is for a pop-up menu button; otherwise, FALSE.

Remarks

Called by the framework when the menu image for the ribbon element is drawn.

virtual BOOL OnDrawMenuImage(
    CDC* pDC,  
    CRect rect);

Parameters

[in] pDC
Pointer to a device context.

[in] rect
Menu image rectangle.

Return Value

Always returns TRUE to indicate the image was drawn.

Remarks

Called by the framework to draw the ribbon element in a commands list box.

virtual void OnDrawOnList(
    CDC* pDC,  
    CString strText,  
    int nTextOffset,  
    CRect rect,  
    BOOL bIsSelected,  
    BOOL bHighlighted);

Parameters

[in] pDC
Pointer to a device context for the ribbon element.

[in] strText
The display text.

[in] nTextOffset
Distance, in pixels, from the left side of the list box to the display text.

[in] rect
The display rectangle for the ribbon element.

[in] bIsSelected
This parameter is not used.

[in] bHighlighted
This parameter is not used.

Remarks

The commands list box displays ribbon elements to enable users to customize the quick access toolbar.

Called by the framework when the user presses a keytip and the ribbon element has the focus.

virtual BOOL OnKey(BOOL bIsMenuKey);

Parameters

[in] bIsMenuKey
TRUE if the keytip displays a pop-up menu; otherwise, FALSE.

Return Value

TRUE if the event was handled; otherwise FALSE.

Remarks

Called by the framework when the user presses a menu keytip on the main panel.

virtual BOOL OnMenuKey(UINT nUpperChar);

Parameters

[in] nUpperChar
This parameter is not used.

Return Value

Always returns FALSE.

Remarks

By default this method always returns FALSE. Override this method to respond when a user presses a menu keytip on the main panel.

Called by the framework when the user presses a shortcut key.

virtual BOOL OnProcessKey(UINT nChar);

Parameters

[in] nChar
This parameter is not used.

Return Value

Always returns FALSE.

Remarks

Override this method if you want the ribbon element to process a shortcut key.

Called by the framework when the layout changes direction.

virtual void OnRTLChanged(BOOL bIsRTL);

Parameters

[in] bIsRTL
This parameter is not used.

Remarks

By default this method does nothing. Override this method to adjust the ribbon element when the layout changes direction. The default layout direction is left-to-right.

Called by the framework when a ribbon element receives or loses the input focus.

virtual void OnSetFocus(BOOL B);

Remarks

Override this method in a derived class if you want your application to handle a change in the focus of a ribbon element.

Called by the framework to show or hide the ribbon element.

virtual void OnShow(BOOL bShow);

Parameters

[in] bShow
This parameter is not used.

Remarks

By default this method does nothing. Override this method to show or hide the ribbon element.

Called by the framework before the ribbon element shows a pop-up menu.

virtual void OnShowPopupMenu();

Remarks

This method notifies the parent window of the ribbon bar that the ribbon element will show a pop-up menu.

Closes the pop-up menu for the ribbon element and sends a close message to the parent menu.

void PostMenuCommand(UINT uiCmdId);

Parameters

[in] uiCmdId
The parameter is not used.

Remarks

The close message is only sent if the ribbon element is located on a pop-up menu.

Updates the display for the ribbon element.

virtual void Redraw();  

Remarks

This method redraws the display rectangle for the ribbon element by calling CWnd::RedrawWindow with the RDW_INVALIDATE, RDW_ERASE, and RDW_UPDATENOW flags set.

Sets the accessibility data for the ribbon element.

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

Parameters

pParent
The parent window for the ribbon element.

data
The accessibility data for the ribbon element.

Return Value

Always returns TRUE.

Remarks

By default this method sets the accessibility data for the ribbon element and always returns TRUE. Override this method to set the accessibility data and return a value that indicates success or failure.

Sets the display size for the ribbon element.

virtual void SetCompactMode(BOOL bCompactMode = TRUE);

Parameters

[in] bCompactMode
TRUE to reduce the display size of the ribbon element; FALSE to increase the display size of the ribbon element.

Remarks

The following table summarizes the logic for this method.

bCompactModeCurrent ribbon element sizeNew ribbon element size
TRUECompactNo change.
TRUEIntermediateCompact if it is possible.
TRUELargeIntermediate if it is possible.
FALSECompactIntermediate if it is possible; otherwise large.

Associates a data item with the ribbon element.

void SetData(DWORD_PTR dwData);

Parameters

[in] dwData
The data value.

Sets the ribbon element to appear as a pop-up command.

void SetDefaultMenuLook(BOOL bIsDefaultMenuLook = TRUE);

Parameters

[in] bIsDefaultMenuLook
TRUE to set the ribbon element to appear as a pop-up command; otherwise FALSE.

Remarks

Sets the description for the ribbon element.

virtual void SetDescription(LPCTSTR lpszText);

Parameters

[in] lpszText
The description for the ribbon element.

Remarks

The framework displays the new description either on the status bar, or in the tooltip, or under the menu button.

Sets the command ID of the ribbon element.

virtual void SetID(UINT nID);

Parameters

[in] nID
The command ID.

Sets the initial display size for the ribbon element.

virtual void SetInitialMode(BOOL bOneRow = FALSE);

Parameters

[in] bOneRow
TRUE to limit the display size for the ribbon element to compact or intermediate; otherwise, FALSE.

Remarks

The display size of ribbon elements can be compact, intermediate, or large.

Sets the keytips for the ribbon element.

virtual void SetKeys(
    LPCTSTR lpszKeys,  
    LPCTSTR lpszMenuKeys=NULL);

Parameters

[in] lpszKeys
The keytip for the ribbon element.

[in] lpszMenuKeys
The keytip for the pop-up menu of the ribbon element.

Sets the original ribbon element for the ribbon element.

virtual void SetOriginal(CMFCRibbonBaseElement* pOriginal);

Parameters

[in] pOriginal
Pointer to a ribbon element.

Remarks

Ribbon elements that are copied to another container retain a pointer to the original ribbon element.

Sets the parent category for the ribbon element.

virtual void SetParentCategory(CMFCRibbonCategory* pParent);

Parameters

[in] pParent
Pointer to a ribbon category.

Remarks

The tabbed groups in ribbon controls are called categories.

Sets the parent menu container for the ribbon element.

virtual void SetParentMenu(CMFCRibbonPanelMenuBar* pMenuBar);

Parameters

[in] pMenuBar
The parent menu.

Remarks

Sets the parent ribbon bar for the ribbon element.

virtual void SetParentRibbonBar(CMFCRibbonBar* pRibbonBar);

Parameters

[in] pRibbonBar
Pointer to the parent ribbon bar.

Remarks

Sets the dimensions of the display rectangle for the ribbon element.

void SetRect(CRect rect);

Parameters

[in] rect
The dimensions of the rectangle.

Remarks

Sets the text and keytip for the ribbon element.

virtual void SetText(LPCTSTR lpszText);

Parameters

[in] lpszText
The text and keytip for the ribbon element.

Remarks

To set the keytip for the ribbon element, append the newline escape sequence followed by the keytip characters to lpszText.

Example

//Set the text for the ribbon element  
SetText(_T("Margins"))  
//Set the text and a single-letter keytip  
SetText(_T("Margins\nm"))  
//Set the text and a multiple-letter keytip  
SetText(_T("Line Numbers\nln"))  

Sets the text for the ribbon element to display on the right.

virtual void SetTextAlwaysOnRight(BOOL bSet = TRUE);

Parameters

[in] bSet
TRUE to display the text on the right; otherwise FALSE.

Remarks

Sets the tooltip text for the ribbon element.

virtual void SetToolTipText(LPCTSTR lpszText);

Parameters

[in] lpszText
The tooltip text.

Sets the visibility of the ribbon element.

void SetVisible(BOOL bIsVisible);

Parameters

[in] bIsVisible
TRUE to display the ribbon element; FALSE to hide the ribbon element.

Remarks

Stretches the width of the ribbon element.

virtual void StretchHorizontally();

Remarks

By default this method generates an assertion failure in debug builds and therefore should not be called. Override this method to stretch the width of the ribbon element.

Changes the display height of the ribbon element to the specified row height.

virtual BOOL StretchToWholeRow(
    CDC* pDC,  
    int nHeight);

Parameters

[in] pDC
This parameter is not used.

[in] nHeight
The height of the row.

Return Value

TRUE if the display height was set; otherwise, FALSE.

Remarks

Override this method to change the display height of the ribbon element to the specified row height.

Updates the tooltip text by using the command resource for the ribbon element.

virtual void UpdateTooltipInfo();

Remarks

Indicates whether the parent element has keyboard focus.

virtual BOOL HasFocus() const;  

Return Value

TRUE if the ribbon element is focused; otherwise FALSE.

Remarks

Hierarchy Chart
Classes

Show: