CMFCRibbonBaseElement Class
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.
Syntax
class CMFCRibbonBaseElement : public CObject
Members
Public Constructors
| Name | Description |
|---|---|
CMFCRibbonBaseElement |
Constructs a CMFCRibbonBaseElement object. |
Public Methods
| Name | Description |
|---|---|
| CMFCRibbonBaseElement::AddToKeyList | Adds a keytip for the ribbon element to an array of keytips. |
| CMFCRibbonBaseElement::AddToListBox | Adds a ribbon element to the specified ribbon commands list box. |
| CMFCRibbonBaseElement::CanBeAddedToQuickAccessToolBar | Indicates whether the ribbon element can be added to the quick access toolbar. |
| CMFCRibbonBaseElement::CanBeCompacted | Indicates whether the size of the ribbon element can be compact. |
| CMFCRibbonBaseElement::CanBeStretched | Indicates whether the height of the ribbon element can increase vertically to the height of a ribbon row. |
| CMFCRibbonBaseElement::CanBeStretchedHorizontally | Indicates whether the width of the ribbon element can change. |
| CMFCRibbonBaseElement::CleanUpSizes | Cleans up the dimension settings for the ribbon element. |
| CMFCRibbonBaseElement::ClosePopupMenu | Closes the popup menu for the ribbon element. |
| CMFCRibbonBaseElement::CopyFrom | Copies the state of the specified CMFCRibbonBaseElement to the current object. |
| CMFCRibbonBaseElement::DestroyCtrl | Destroys the ribbon element. |
| CMFCRibbonBaseElement::DrawImage | Draws the image for the ribbon element. |
| CMFCRibbonBaseElement::Find | Returns the specified pointer to the ribbon element if it points to the current object. |
| CMFCRibbonBaseElement::FindByData | Retrieves a pointer to the ribbon element if it contains the specified data. |
| CMFCRibbonBaseElement::FindByID | Retrieves a pointer to the ribbon element if that element is identified by the specified command ID. |
| CMFCRibbonBaseElement::FindByOriginal | Retrieves a pointer to the ribbon element if its original ribbon element matches the specified ribbon element. |
| CMFCRibbonBaseElement::GetCompactSize | Returns the compact size of the ribbon element. |
| CMFCRibbonBaseElement::GetData | Retrieves the user-defined data associated with the ribbon element. |
| CMFCRibbonBaseElement::GetDescription | Returns the description of the ribbon element. |
| CMFCRibbonBaseElement::GetDroppedDown | Retrieves a pointer to the ribbon element if its pop-up menu is dropped down. |
| CMFCRibbonBaseElement::GetElements | Adds the current ribbon element to the specified array. |
| CMFCRibbonBaseElement::GetElementsByID | Adds the current ribbon element to the specified array if the current ribbon element contains the specified command ID. |
| CMFCRibbonBaseElement::GetHighlighted | Retrieves a pointer to the ribbon element if it is highlighted. |
| CMFCRibbonBaseElement::GetID | Returns the command ID of the ribbon element. |
| CMFCRibbonBaseElement::GetImageSize | Returns the image size of the ribbon element. |
| CMFCRibbonBaseElement::GetIntermediateSize | Returns the size of the ribbon element in its intermediate state. |
| CMFCRibbonBaseElement::GetKeys | Returns the keytip associated with the ribbon element. |
| CMFCRibbonBaseElement::GetKeyTipRect | Retrieves the keytip boundary rectangle for the ribbon element. |
| CMFCRibbonBaseElement::GetKeyTipSize | Retrieves the size of the keytip text. |
| CMFCRibbonBaseElement::GetLocationInGroup | Indicates the display location of the ribbon element in a ribbon group. |
| CMFCRibbonBaseElement::GetMenuKeys | Returns the keytips associated with a button. |
| CMFCRibbonBaseElement::GetNotifyID | Retrieves the notification command ID for the ribbon element. |
| CMFCRibbonBaseElement::GetOriginal | Retrieves the original ribbon element. |
| CMFCRibbonBaseElement::GetParentCategory | Retrieves the ribbon category for the ribbon element. |
| CMFCRibbonBaseElement::GetParentPanel | Retrieves the ribbon panel that contains the ribbon element. |
| CMFCRibbonBaseElement::GetParentRibbonBar | Retrieves the parent ribbon bar for the ribbon element. |
| CMFCRibbonBaseElement::GetParentWnd | Retrieves the parent window for the ribbon element. |
| CMFCRibbonBaseElement::GetPressed | Retrieves a pointer to the ribbon element if the user currently presses it. |
| CMFCRibbonBaseElement::GetQuickAccessToolBarID | Retrieves the command ID of the ribbon element when it is located in the quick access toolbar. |
| CMFCRibbonBaseElement::GetRect | Returns the bounding rectangle of the ribbon element. |
| CMFCRibbonBaseElement::GetRegularSize | Returns the regular size of the ribbon element. |
| CMFCRibbonBaseElement::GetSize | Returns the current size of the ribbon element. |
| CMFCRibbonBaseElement::GetText | Returns the text associated with the ribbon element. |
| CMFCRibbonBaseElement::GetToolTipText | Returns tooltip text of the ribbon element. |
| CMFCRibbonBaseElement::GetTopLevelRibbonBar | Retrieves the top level ribbon bar for the ribbon element. |
| CMFCRibbonBaseElement::HasCompactMode | Specifies whether the ribbon element has a compact mode. |
| CMFCRibbonBaseElement::HasFocus | Indicates whether the parent element has keyboard focus. |
| CMFCRibbonBaseElement::HasIntermediateMode | Specifies whether the ribbon element has an intermediate mode. |
| CMFCRibbonBaseElement::HasLargeMode | Specifies whether the ribbon element has a large mode. |
| CMFCRibbonBaseElement::HasMenu | Indicates whether the ribbon element has a menu. |
| CMFCRibbonBaseElement::HitTest | Retrieves a pointer to the ribbon element if the specified point is located in it. |
| CMFCRibbonBaseElement::IsAlignByColumn | Indicates whether the ribbon element is aligned vertically with other ribbon elements. |
| CMFCRibbonBaseElement::IsAlwaysLargeImage | Indicates whether the ribbon element image size is always large. |
| CMFCRibbonBaseElement::IsAutoRepeatMode | Indicates whether the ribbon element is in auto repeat mode. |
| CMFCRibbonBaseElement::IsChecked | Specifies whether the ribbon element is checked. |
| CMFCRibbonBaseElement::IsCompactMode | Specifies whether the ribbon element is in a compact mode. |
| CMFCRibbonBaseElement::IsDefaultMenuLook | |
| CMFCRibbonBaseElement::IsDisabled | Specifies whether the ribbon element is disabled. |
| CMFCRibbonBaseElement::IsDroppedDown | Determines whether the ribbon element displays a popup menu and is dropped down. |
| CMFCRibbonBaseElement::IsFocused | Specifies whether the ribbon element has the focus. |
| CMFCRibbonBaseElement::IsGalleryIcon | Indicates whether the ribbon element is contained in a ribbon gallery. |
| CMFCRibbonBaseElement::IsHighlighted | Specifies whether ribbon element is highlighted. |
| CMFCRibbonBaseElement::IsIntermediateMode | Indicates whether the current image for the ribbon element is intermediate size. |
| CMFCRibbonBaseElement::IsLargeMode | Indicates whether the current image for the ribbon element is large sized. |
| CMFCRibbonBaseElement::IsMenuMode | Indicates whether the ribbon element is contained in a menu. |
| CMFCRibbonBaseElement::IsPressed | Indicates whether the user has clicked the ribbon element. |
| CMFCRibbonBaseElement::IsQATMode | Indicates whether the ribbon element is contained in the quick access toolbar. |
| CMFCRibbonBaseElement::IsSeparator | Indicates whether the ribbon element is a display separator. |
| CMFCRibbonBaseElement::IsShowGroupBorder | Indicates whether the ribbon element is contained in a group that displays a common border. |
| CMFCRibbonBaseElement::IsShowTooltipOnBottom | Indicates whether the tooltip is displayed under the ribbon element. |
| CMFCRibbonBaseElement::IsTabStop | Indicates whether the ribbon element can be selected with the keyboard. |
| CMFCRibbonBaseElement::IsTextAlwaysOnRight | Indicates whether the text for the ribbon element is displayed on the right. |
| CMFCRibbonBaseElement::IsVisible | Indicates whether the ribbon element is currently displayed. |
| CMFCRibbonBaseElement::IsWholeRowHeight | Indicates whether the display heigth of the ribbon element is the same as the display height of the ribbon panel that contains it. |
| CMFCRibbonBaseElement::NotifyCommand | Sends a command notification to the parent window of the ribbon element. |
| CMFCRibbonBaseElement::NotifyHighlightListItem | Notifies the parent window of the ribbon bar when a user highlights a ribbon element that is located in a list. |
| CMFCRibbonBaseElement::OnAddToQAToolbar | Adds the ribbon element to the specified quick access toolbar. |
| CMFCRibbonBaseElement::OnAfterChangeRect | Updates the tooltip for the ribbon element. |
| CMFCRibbonBaseElement::OnAutoRepeat | Updates the ribbon element in response to sustained user input. |
| CMFCRibbonBaseElement::OnCalcTextSize | Calculates the size of the text for the ribbon element. |
| CMFCRibbonBaseElement::OnChangeMenuHighlight | Called by the framework when the highlight changes for a ribbon element that is located in a menu. |
| CMFCRibbonBaseElement::OnDraw | Called by the framework to draw the ribbon element. |
| CMFCRibbonBaseElement::OnDrawKeyTip | Called by the framework to draw the keytip for the ribbon element. |
| CMFCRibbonBaseElement::OnDrawMenuImage | Called by the framework when the menu image for the ribbon element is drawn. |
| CMFCRibbonBaseElement::OnDrawOnList | Called by the framework to draw the ribbon element in a commands list box. |
| CMFCRibbonBaseElement::OnKey | Called by the framework when the user presses a keytip and the ribbon element has the focus. |
| CMFCRibbonBaseElement::OnMenuKey | |
| CMFCRibbonBaseElement::OnRTLChanged | Called by the framework when the layout changes direction. |
| CMFCRibbonBaseElement::OnShow | Called by the framework to show or hide the ribbon element. |
| CMFCRibbonBaseElement::OnShowPopupMenu | Called by the framework when the ribbon element is going to display a popup menu. |
| CMFCRibbonBaseElement::PostMenuCommand | |
| CMFCRibbonBaseElement::Redraw | Updates the display for the ribbon element. |
| CMFCRibbonBaseElement::SetACCData | Sets the accessibility data for the ribbon element. |
| CMFCRibbonBaseElement::SetCompactMode | Sets the display size for the ribbon element. |
| CMFCRibbonBaseElement::SetData | Associates a data item with the ribbon element. |
| CMFCRibbonBaseElement::SetDefaultMenuLook | |
| CMFCRibbonBaseElement::SetDescription | Sets the description for the ribbon element. |
| CMFCRibbonBaseElement::SetID | Sets the command ID of the ribbon element. |
| CMFCRibbonBaseElement::SetInitialMode | Sets the initial display size for the ribbon element. |
| CMFCRibbonBaseElement::SetKeys | Sets a keytip for the ribbon element. |
| CMFCRibbonBaseElement::SetOriginal | Sets the original ribbon element for the ribbon element. |
| CMFCRibbonBaseElement::SetParentCategory | Sets the parent category for the ribbon element. |
| CMFCRibbonBaseElement::SetParentMenu | Sets the parent menu container for the ribbon element. |
| CMFCRibbonBaseElement::SetParentRibbonBar | Sets the parent ribbon bar for the ribbon element. |
| CMFCRibbonBaseElement::SetRect | Sets the dimensions fot he display rectangle for the ribbon element. |
| CMFCRibbonBaseElement::SetText | Sets the text for the ribbon element. |
| CMFCRibbonBaseElement::SetTextAlwaysOnRight | Sets the text for the ribbon element to display on the right. |
| CMFCRibbonBaseElement::SetToolTipText | Sets the tooltip text for the ribbon element. |
| CMFCRibbonBaseElement::SetVisible | Sets the visibility state of the ribbon element. |
| CMFCRibbonBaseElement::StretchHorizontally | Stretches the width of the ribbon element. |
| CMFCRibbonBaseElement::StretchToWholeRow | Changes the display height of the ribbon element to the specified row height. |
| CMFCRibbonBaseElement::UpdateTooltipInfo | Updates the tooltip text by using the command resource for the ribbon element. |
Protected Methods
| Name | Description |
|---|---|
| CMFCRibbonBaseElement::OnProcessKey | Called by the framework when the user presses a shortcut key. |
| CMFCRibbonBaseElement::OnSetFocus | Called by the framework when a ribbon element receives or loses the input focus. |
Remarks
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:
RibbonImageLargeRibbonImageSmall
Depending on its size, a ribbon element displays either a small or large image.
Example
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"));
Inheritance Hierarchy
Requirements
Header: afxbaseribbonelement.h
CMFCRibbonBaseElement::AddToKeyList
Adds a keytip for the ribbon element to an array of keytips.
virtual void AddToKeyList(
CArray<CMFCRibbonKeyTip*, CMFCRibbonKeyTip*>& arElems);
Parameters
arElems
[in] 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.
CMFCRibbonBaseElement::AddToListBox
Adds a ribbon element to the specified ribbon commands list box.
virtual int AddToListBox(
CMFCRibbonCommandsListBox* pWndListBox,
BOOL bDeep);
Parameters
pWndListBox
[in] Pointer to a commands list box.
bDeep
[in] 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.
CMFCRibbonBaseElement::CanBeAddedToQuickAccessToolBar
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
CMFCRibbonBaseElement::CanBeCompacted
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.
CMFCRibbonBaseElement::CanBeStretched
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.
CMFCRibbonBaseElement::CanBeStretchedHorizontally
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.
CMFCRibbonBaseElement::CleanUpSizes
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.
CMFCRibbonBaseElement::ClosePopupMenu
Closes the pop-up menu for the ribbon element.
virtual void ClosePopupMenu();
Remarks
CMFCRibbonBaseElement::CopyFrom
Copies the state of the specified CMFCRibbonBaseElement to the current object.
virtual void CopyFrom(const CMFCRibbonBaseElement& src);
Parameters
src
[in] The source CMFCRibbonBaseElement object.
Remarks
CMFCRibbonBaseElement::DestroyCtrl
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.
CMFCRibbonBaseElement::DrawImage
Draws the image for the ribbon element.
virtual void DrawImage(
CDC* pDC,
RibbonImageType type,
CRect rectImage);
Parameters
pDC
[in] Pointer to a device context.
type
[in] An image type enumerated value. See the Remarks section for a list of possible values.
rectImage
[in] 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:
| Value | Description |
|---|---|
RibbonImageLarge |
Large 32x32 pixel image size. |
RibbonImageSmall |
Small 16x16 pixel image size. |
CMFCRibbonBaseElement::Find
Returns the specified pointer if it points to the current object.
virtual CMFCRibbonBaseElement* Find(const CMFCRibbonBaseElement* pElement);
Parameters
pElement
[in] Pointer to a ribbon element.
Return Value
A pointer to the ribbon element if pElement points to the current object; otherwise NULL.
Remarks
CMFCRibbonBaseElement::FindByData
Retrieves a pointer to the ribbon element if it contains the specified data.
virtual CMFCRibbonBaseElement* FindByData(DWORD_PTR dwData);
Parameters
dwData
[in] The data associated with a ribbon element.
Return Value
A pointer to the ribbon element if it contains the specified data; otherwise NULL.
Remarks
CMFCRibbonBaseElement::FindByID
Retrieves a pointer to the ribbon element if that element is identified by the specified command ID.
virtual CMFCRibbonBaseElement* FindByID(UINT uiCmdID);
Parameters
uiCmdID
[in] 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
CMFCRibbonBaseElement::FindByOriginal
Retrieves a pointer to the current ribbon element if its original ribbon element matches the specified ribbon element.
virtual CMFCRibbonBaseElement* FindByOriginal(CMFCRibbonBaseElement* pOriginal);
Parameters
pOriginal
[in] 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.
CMFCRibbonBaseElement::GetCompactSize
Returns the compact size of the ribbon element.
virtual CSize GetCompactSize(CDC* pDC);
Parameters
pDC
[in] A pointer to a device context.
Return Value
The compact size of a ribbon element.
Note
The compact size means that the ribbon element is truncated (it displays a small image, or an image without a text).
CMFCRibbonBaseElement::GetData
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.
CMFCRibbonBaseElement::GetDescription
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.
CMFCRibbonBaseElement::GetDroppedDown
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
CMFCRibbonBaseElement::GetElements
Adds the current ribbon element to the specified array.
virtual void GetElements(
CArray<CMFCRibbonBaseElement*, CMFCRibbonBaseElement*>& arElements);
Parameters
arElements
[in, out] An array of ribbon elements.
Remarks
CMFCRibbonBaseElement::GetElementsByID
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
uiCmdID
[in] Command ID of a ribbon element.
arElements
[in] An array of ribbon elements.
Remarks
CMFCRibbonBaseElement::GetHighlighted
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
CMFCRibbonBaseElement::GetID
Returns the command ID of the ribbon element.
UINT GetID() const;
Return Value
The command ID of the ribbon element.
CMFCRibbonBaseElement::GetImageSize
Returns the image size of the ribbon element.
virtual CSize GetImageSize(RibbonImageType R) const;
Return Value
The image size of the ribbon element.
CMFCRibbonBaseElement::GetIntermediateSize
Returns the size of the ribbon element in its intermediate state.
virtual CSize GetIntermediateSize(CDC* pDC);
Parameters
pDC
[in] A pointer to a device context.
Return Value
The size of the ribbon element in its intermediate state.
CMFCRibbonBaseElement::GetKeys
Returns the keytip associated with the ribbon element.
LPCTSTR GetKeys() const;
Return Value
A keytip associated with the ribbon element.
CMFCRibbonBaseElement::GetKeyTipRect
Retrieves the keytip boundary rectangle for the ribbon element.
virtual CRect GetKeyTipRect(
CDC* pDC,
BOOL bIsMenu);
Parameters
pDC
[in] Pointer to a device context.
bIsMenu
[in] 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.
CMFCRibbonBaseElement::GetKeyTipSize
Retrieves the size of the keytip text.
virtual CSize GetKeyTipSize(CDC* pDC);
Parameters
pDC
[in] Pointer to a device context.
Return Value
The size of the keytip text.
Remarks
CMFCRibbonBaseElement::GetLocationInGroup
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.
| Value | Description |
|---|---|
RibbonElementNotInGroup |
The ribbon element is not contained in a ribbon group. |
RibbonElementSingleInGroup |
The ribbon element is displayed as the only item in a ribbon group. |
RibbonElementFirstInGroup |
The ribbon element is displayed on the left end of a ribbon group. |
RibbonElementLastInGroup |
The ribbon element is displayed on the right end of a ribbon group. |
RibbonElementMiddleInGroup |
The ribbon element is not displayed on either end of a ribbon group. |
Remarks
Ribbon element groups are only aligned horizontally.
CMFCRibbonBaseElement::GetMenuKeys
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.
CMFCRibbonBaseElement::GetNotifyID
Retrieves the notification command ID for the ribbon element.
virtual UINT GetNotifyID();
Return Value
The notification command ID.
Remarks
CMFCRibbonBaseElement::GetOriginal
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.
CMFCRibbonBaseElement::GetParentCategory
Retrieves the ribbon category for the ribbon element.
CMFCRibbonCategory* GetParentCategory() const;
Return Value
A pointer to the ribbon category.
Remarks
CMFCRibbonBaseElement::GetParentPanel
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
CMFCRibbonBaseElement::GetParentRibbonBar
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
CMFCRibbonBaseElement::GetParentWnd
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.
CMFCRibbonBaseElement::GetPressed
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
CMFCRibbonBaseElement::GetQuickAccessToolBarID
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
CMFCRibbonBaseElement::GetRect
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.
CMFCRibbonBaseElement::GetRegularSize
Returns the regular size of the ribbon element.
virtual CSize GetRegularSize(CDC* pDC) = 0;
Parameters
pDC
[in] A pointer to a device context.
Return Value
The regular size of the ribbon element.
Remarks
Note
The regular size is the maximal possible size of the ribbon element.
CMFCRibbonBaseElement::GetSize
Returns the current size of the ribbon element.
virtual CSize GetSize(CDC* pDC);
Parameters
pDC
[in] A pointer to a device context.
Return Value
The current size of the ribbon element.
CMFCRibbonBaseElement::GetText
Returns the text associated with the ribbon element.
LPCTSTR GetText() const;
Return Value
The text associated with the ribbon element.
CMFCRibbonBaseElement::GetToolTipText
Returns tooltip text of the ribbon element.
virtual CString GetToolTipText() const;
Return Value
The tooltip text of the ribbon element.
CMFCRibbonBaseElement::GetTopLevelRibbonBar
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
CMFCRibbonBaseElement::HasCompactMode
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
Note
In the compact mode, an element displays a small image only.
CMFCRibbonBaseElement::HasIntermediateMode
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
CMFCRibbonBaseElement::HasLargeMode
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.
CMFCRibbonBaseElement::HasMenu
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.
CMFCRibbonBaseElement::HitTest
Retrieves a pointer to the ribbon element if the specified point is located in it.
virtual CMFCRibbonBaseElement* HitTest(CPoint point);
Parameters
point
[in] 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.
CMFCRibbonBaseElement::IsAlignByColumn
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.
CMFCRibbonBaseElement::IsAlwaysLargeImage
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.
CMFCRibbonBaseElement::IsAutoRepeatMode
Indicates whether the ribbon element is in auto repeat mode.
virtual BOOL IsAutoRepeatMode(int& nDelay) const;
Parameters
nDelay
[in] 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.
CMFCRibbonBaseElement::IsChecked
Specifies whether the ribbon element is checked.
virtual BOOL IsChecked() const;
Return Value
TRUE if the ribbon element is checked; otherwise FALSE.
CMFCRibbonBaseElement::IsCompactMode
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.
CMFCRibbonBaseElement::IsDefaultMenuLook
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
CMFCRibbonBaseElement::IsDisabled
Specifies whether the ribbon element is disabled.
virtual BOOL IsDisabled() const;
Return Value
TRUE if the ribbon element is disabled; otherwise FALSE.
CMFCRibbonBaseElement::IsDroppedDown
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.
CMFCRibbonBaseElement::IsFocused
Specifies whether the ribbon element has the focus.
virtual BOOL IsFocused() const;
Return Value
TRUE if the ribbon element has the focus; otherwise FALSE.
CMFCRibbonBaseElement::IsGalleryIcon
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.
CMFCRibbonBaseElement::IsHighlighted
Specifies whether ribbon element is highlighted.
virtual BOOL IsHighlighted() const;
Return Value
TRUE if the ribbon element is highlighted; otherwise FALSE.
Remarks
CMFCRibbonBaseElement::IsIntermediateMode
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.
CMFCRibbonBaseElement::IsLargeMode
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.
CMFCRibbonBaseElement::IsMenuMode
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
CMFCRibbonBaseElement::IsPressed
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.
CMFCRibbonBaseElement::IsQATMode
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
CMFCRibbonBaseElement::IsSeparator
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
CMFCRibbonBaseElement::IsShowGroupBorder
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
CMFCRibbonBaseElement::IsShowTooltipOnBottom
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
CMFCRibbonBaseElement::IsTabStop
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.
CMFCRibbonBaseElement::IsTextAlwaysOnRight
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
CMFCRibbonBaseElement::IsVisible
Indicates whether the ribbon element is currently displayed.
BOOL IsVisible() const;
Return Value
TRUE if the ribbon element is currently displayed; otherwise, FALSE.
Remarks
CMFCRibbonBaseElement::IsWholeRowHeight
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.
CMFCRibbonBaseElement::NotifyCommand
Sends a command notification to the parent window of the ribbon element.
BOOL NotifyCommand(BOOL bWithDelay = FALSE);
Parameters
bWithDelay
[in] 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
CMFCRibbonBaseElement::NotifyHighlightListItem
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
nIndex
[in] The index of the ribbon element in the list.
Remarks
CMFCRibbonBaseElement::OnAddToQAToolbar
Adds the ribbon element to the specified quick access toolbar.
virtual BOOL OnAddToQAToolbar(CMFCRibbonQuickAccessToolBar& qat);
Parameters
qat
[in] The quick access toolbar.
Return Value
Always returns TRUE indicating the ribbon element was added to the quick access toolbar.
Remarks
CMFCRibbonBaseElement::OnAfterChangeRect
Updates the tooltip for the ribbon element.
virtual void OnAfterChangeRect(CDC* pDC);
Parameters
pDC
[in] 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.
CMFCRibbonBaseElement::OnAutoRepeat
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.
CMFCRibbonBaseElement::OnCalcTextSize
Calculates the size of the text for the ribbon element.
virtual void OnCalcTextSize(CDC* pDC);
Parameters
pDC
[in] 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.
CMFCRibbonBaseElement::OnChangeMenuHighlight
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
pPanelMenuBar
[in] This parameter is not used.
pHot
[in] 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.
CMFCRibbonBaseElement::OnDraw
Called by the framework to draw the ribbon element.
virtual void OnDraw(CDC* pDC) = 0;
Parameters
pDC
[in] 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.
CMFCRibbonBaseElement::OnDrawKeyTip
Called by the framework to draw the keytip for the ribbon element.
virtual void OnDrawKeyTip(
CDC* pDC,
const CRect& rect,
BOOL bIsMenu);
Parameters
pDC
[in] Pointer to a device context.
rect
[in] Boundary rectangle for the keytip.
bIsMenu
[in] TRUE if the keytip is for a pop-up menu button; otherwise, FALSE.
Remarks
CMFCRibbonBaseElement::OnDrawMenuImage
Called by the framework when the menu image for the ribbon element is drawn.
virtual BOOL OnDrawMenuImage(
CDC* pDC,
CRect rect);
Parameters
pDC
[in] Pointer to a device context.
rect
[in] Menu image rectangle.
Return Value
Always returns TRUE to indicate the image was drawn.
Remarks
CMFCRibbonBaseElement::OnDrawOnList
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
pDC
[in] Pointer to a device context for the ribbon element.
strText
[in] The display text.
nTextOffset
[in] Distance, in pixels, from the left side of the list box to the display text.
rect
[in] The display rectangle for the ribbon element.
bIsSelected
[in] This parameter is not used.
bHighlighted
[in] This parameter is not used.
Remarks
The commands list box displays ribbon elements to enable users to customize the quick access toolbar.
CMFCRibbonBaseElement::OnKey
Called by the framework when the user presses a keytip and the ribbon element has the focus.
virtual BOOL OnKey(BOOL bIsMenuKey);
Parameters
bIsMenuKey
[in] TRUE if the keytip displays a pop-up menu; otherwise, FALSE.
Return Value
TRUE if the event was handled; otherwise FALSE.
Remarks
CMFCRibbonBaseElement::OnMenuKey
Called by the framework when the user presses a menu keytip on the main panel.
virtual BOOL OnMenuKey(UINT nUpperChar);
Parameters
nUpperChar
[in] 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.
CMFCRibbonBaseElement::OnProcessKey
Called by the framework when the user presses a shortcut key.
virtual BOOL OnProcessKey(UINT nChar);
Parameters
nChar
[in] 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.
CMFCRibbonBaseElement::OnRTLChanged
Called by the framework when the layout changes direction.
virtual void OnRTLChanged(BOOL bIsRTL);
Parameters
bIsRTL
[in] 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.
CMFCRibbonBaseElement::OnSetFocus
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.
CMFCRibbonBaseElement::OnShow
Called by the framework to show or hide the ribbon element.
virtual void OnShow(BOOL bShow);
Parameters
bShow
[in] This parameter is not used.
Remarks
By default this method does nothing. Override this method to show or hide the ribbon element.
CMFCRibbonBaseElement::OnShowPopupMenu
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.
CMFCRibbonBaseElement::PostMenuCommand
Closes the pop-up menu for the ribbon element and sends a close message to the parent menu.
void PostMenuCommand(UINT uiCmdId);
Parameters
uiCmdId
[in] The parameter is not used.
Remarks
The close message is only sent if the ribbon element is located on a pop-up menu.
CMFCRibbonBaseElement::Redraw
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.
CMFCRibbonBaseElement::SetACCData
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.
CMFCRibbonBaseElement::SetCompactMode
Sets the display size for the ribbon element.
virtual void SetCompactMode(BOOL bCompactMode = TRUE);
Parameters
bCompactMode
[in] 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.
| bCompactMode | Current ribbon element size | New ribbon element size |
|---|---|---|
| TRUE | Compact | No change. |
| TRUE | Intermediate | Compact if it is possible. |
| TRUE | Large | Intermediate if it is possible. |
| FALSE | Compact | Intermediate if it is possible; otherwise large. |
CMFCRibbonBaseElement::SetData
Associates a data item with the ribbon element.
void SetData(DWORD_PTR dwData);
Parameters
dwData
[in] The data value.
CMFCRibbonBaseElement::SetDefaultMenuLook
Sets the ribbon element to appear as a pop-up command.
void SetDefaultMenuLook(BOOL bIsDefaultMenuLook = TRUE);
Parameters
bIsDefaultMenuLook
[in] TRUE to set the ribbon element to appear as a pop-up command; otherwise FALSE.
Remarks
CMFCRibbonBaseElement::SetDescription
Sets the description for the ribbon element.
virtual void SetDescription(LPCTSTR lpszText);
Parameters
lpszText
[in] 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.
CMFCRibbonBaseElement::SetID
Sets the command ID of the ribbon element.
virtual void SetID(UINT nID);
Parameters
nID
[in] The command ID.
CMFCRibbonBaseElement::SetInitialMode
Sets the initial display size for the ribbon element.
virtual void SetInitialMode(BOOL bOneRow = FALSE);
Parameters
bOneRow
[in] 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.
CMFCRibbonBaseElement::SetKeys
Sets the keytips for the ribbon element.
virtual void SetKeys(
LPCTSTR lpszKeys,
LPCTSTR lpszMenuKeys=NULL);
Parameters
lpszKeys
[in] The keytip for the ribbon element.
lpszMenuKeys
[in] The keytip for the pop-up menu of the ribbon element.
CMFCRibbonBaseElement::SetOriginal
Sets the original ribbon element for the ribbon element.
virtual void SetOriginal(CMFCRibbonBaseElement* pOriginal);
Parameters
pOriginal
[in] Pointer to a ribbon element.
Remarks
Ribbon elements that are copied to another container retain a pointer to the original ribbon element.
CMFCRibbonBaseElement::SetParentCategory
Sets the parent category for the ribbon element.
virtual void SetParentCategory(CMFCRibbonCategory* pParent);
Parameters
pParent
[in] Pointer to a ribbon category.
Remarks
The tabbed groups in ribbon controls are called categories.
CMFCRibbonBaseElement::SetParentMenu
Sets the parent menu container for the ribbon element.
virtual void SetParentMenu(CMFCRibbonPanelMenuBar* pMenuBar);
Parameters
pMenuBar
[in] The parent menu.
Remarks
CMFCRibbonBaseElement::SetParentRibbonBar
Sets the parent ribbon bar for the ribbon element.
virtual void SetParentRibbonBar(CMFCRibbonBar* pRibbonBar);
Parameters
pRibbonBar
[in] Pointer to the parent ribbon bar.
Remarks
CMFCRibbonBaseElement::SetRect
Sets the dimensions of the display rectangle for the ribbon element.
void SetRect(CRect rect);
Parameters
rect
[in] The dimensions of the rectangle.
Remarks
CMFCRibbonBaseElement::SetText
Sets the text and keytip for the ribbon element.
virtual void SetText(LPCTSTR lpszText);
Parameters
lpszText
[in] 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"))
CMFCRibbonBaseElement::SetTextAlwaysOnRight
Sets the text for the ribbon element to display on the right.
virtual void SetTextAlwaysOnRight(BOOL bSet = TRUE);
Parameters
bSet
[in] TRUE to display the text on the right; otherwise FALSE.
Remarks
CMFCRibbonBaseElement::SetToolTipText
Sets the tooltip text for the ribbon element.
virtual void SetToolTipText(LPCTSTR lpszText);
Parameters
lpszText
[in] The tooltip text.
CMFCRibbonBaseElement::SetVisible
Sets the visibility of the ribbon element.
void SetVisible(BOOL bIsVisible);
Parameters
bIsVisible
[in] TRUE to display the ribbon element; FALSE to hide the ribbon element.
Remarks
CMFCRibbonBaseElement::StretchHorizontally
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.
CMFCRibbonBaseElement::StretchToWholeRow
Changes the display height of the ribbon element to the specified row height.
virtual BOOL StretchToWholeRow(
CDC* pDC,
int nHeight);
Parameters
pDC
[in] This parameter is not used.
nHeight
[in] 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.
CMFCRibbonBaseElement::UpdateTooltipInfo
Updates the tooltip text by using the command resource for the ribbon element.
virtual void UpdateTooltipInfo();
Remarks
CMFCRibbonBaseElement::HasFocus
Indicates whether the parent element has keyboard focus.
virtual BOOL HasFocus() const;
Return Value
TRUE if the ribbon element is focused; otherwise FALSE.
Remarks
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for