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.
class CMFCRibbonBaseElement : public CObject
| Name | Description |
|---|---|
CMFCRibbonBaseElement |
Constructs a CMFCRibbonBaseElement object. |
| 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 of the 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. |
| 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. |
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.
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"));
Header: afxbaseribbonelement.h
Adds a keytip for the ribbon element to an array of keytips.
virtual void AddToKeyList(
CArray<CMFCRibbonKeyTip*, CMFCRibbonKeyTip*>& arElems);
arElems
[in] Reference to a CArray of keytips.
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);
pWndListBox
[in] Pointer to a commands list box.
bDeep
[in] This parameter is not used.
The zero-based index of the added ribbon element.
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;
TRUE if the element can be added; otherwise, FALSE.
Indicates whether the size of the ribbon element can be compact.
virtual BOOL CanBeCompacted() const;
TRUE if the size of the ribbon element can be compact; otherwise, FALSE.
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();
Always returns TRUE.
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();
Always returns FALSE.
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();
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();
Copies the state of the specified CMFCRibbonBaseElement to the current object.
virtual void CopyFrom(const CMFCRibbonBaseElement& src);
src
[in] The source CMFCRibbonBaseElement object.
Destroys the ribbon element.
virtual void DestroyCtrl();
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);
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.
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. |
Returns the specified pointer if it points to the current object.
virtual CMFCRibbonBaseElement* Find(const CMFCRibbonBaseElement* pElement);
pElement
[in] Pointer to a ribbon element.
A pointer to the ribbon element if pElement points to the current object; otherwise NULL.
Retrieves a pointer to the ribbon element if it contains the specified data.
virtual CMFCRibbonBaseElement* FindByData(DWORD_PTR dwData);
dwData
[in] The data associated with a ribbon element.
A pointer to the ribbon element if it contains the specified data; otherwise NULL.
Retrieves a pointer to the ribbon element if that element is identified by the specified command ID.
virtual CMFCRibbonBaseElement* FindByID(UINT uiCmdID);
uiCmdID
[in] Command ID for a ribbon element.
A pointer to the ribbon element if that element is identified by the specified command ID; otherwise NULL.
Retrieves a pointer to the current ribbon element if its original ribbon element matches the specified ribbon element.
virtual CMFCRibbonBaseElement* FindByOriginal(CMFCRibbonBaseElement* pOriginal);
pOriginal
[in] Pointer to a ribbon element.
A pointer to the ribbon element if its original ribbon element matches the specified ribbon element; otherwise NULL.
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);
pDC
[in] A pointer to a device context.
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).
Retrieves the user-defined data associated with the ribbon element.
DWORD_PTR GetData() const;
The user-defined data associated with the ribbon element.
Returns the description of the ribbon element.
virtual CString GetDescription() const;
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();
A pointer to the ribbon element if its pop-up menu is dropped down; otherwise NULL.
Adds the current ribbon element to the specified array.
virtual void GetElements(
CArray<CMFCRibbonBaseElement*, CMFCRibbonBaseElement*>& arElements);
arElements
[in, out] An array of ribbon elements.
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);
uiCmdID
[in] Command ID of a ribbon element.
arElements
[in] An array of ribbon elements.
Retrieves a pointer to the ribbon element if it is highlighted.
virtual CMFCRibbonBaseElement* GetHighlighted();
A pointer to the ribbon element if it is highlighted; otherwise NULL.
Returns the command ID of the ribbon element.
UINT GetID() const;
The command ID of the ribbon element.
Returns the image size of the ribbon element.
virtual CSize GetImageSize(RibbonImageType R) const;
The image size of the ribbon element.
Returns the size of the ribbon element in its intermediate state.
virtual CSize GetIntermediateSize(CDC* pDC);
pDC
[in] A pointer to a device context.
The size of the ribbon element in its intermediate state.
Returns the keytip associated with the ribbon element.
LPCTSTR GetKeys() const;
A keytip associated with the ribbon element.
Retrieves the keytip boundary rectangle for the ribbon element.
virtual CRect GetKeyTipRect(
CDC* pDC,
BOOL bIsMenu);
pDC
[in] Pointer to a device context.
bIsMenu
[in] TRUE if the ribbon element displays a pop-up menu; otherwise FALSE.
Always returns a rectangle with 0 values.
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);
pDC
[in] Pointer to a device context.
The size of the keytip text.
Indicates the display location of the ribbon element in a ribbon group.
RibbonElementLocation GetLocationInGroup() const;
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. |
Ribbon element groups are only aligned horizontally.
Returns the menu keytip for the ribbon element.
LPCTSTR GetMenuKeys() const;
The menu keytip associated with the ribbon element.
When invoked, a menu keytip displays a pop-up menu.
Retrieves the notification command ID for the ribbon element.
virtual UINT GetNotifyID();
The notification command ID.
Retrieves the original ribbon element.
CMFCRibbonBaseElement* GetOriginal() const;
A pointer to the original ribbon element.
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;
A pointer to the ribbon category.
Retrieves the ribbon panel that contains the ribbon element.
virtual CMFCRibbonPanel* GetParentPanel() const;
A pointer to the ribbon panel that contains the ribbon element.
Retrieves the parent ribbon bar for the ribbon element.
CMFCRibbonBar* GetParentRibbonBar() const;
A pointer to the parent ribbon bar for the ribbon element.
Retrieves the parent window for the ribbon element.
virtual CWnd* GetParentWnd() const;
A pointer to the parent window for the ribbon element if the method was successful; otherwise, NULL.
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();
A pointer to the ribbon element if the user currently presses it; otherwise, NULL.
Retrieves the command ID of the ribbon element when it is located in the quick access toolbar.
virtual UINT GetQuickAccessToolBarID() const;
The command ID of the ribbon element when it is located in the quick access toolbar.
Returns the bounding rectangle of the ribbon element.
CRect GetRect() const;
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;
pDC
[in] A pointer to a device context.
The regular size of the ribbon element.
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);
pDC
[in] A pointer to a device context.
The current size of the ribbon element.
Returns the text associated with the ribbon element.
LPCTSTR GetText() const;
The text associated with the ribbon element.
Returns tooltip text of the ribbon element.
virtual CString GetToolTipText() const;
The tooltip text of the ribbon element.
Retrieves the top level ribbon bar for the ribbon element.
CMFCRibbonBar* GetTopLevelRibbonBar() const;
A pointer to the top level ribbon bar for the ribbon element if the method was successful; otherwise, NULL.
Specifies whether the ribbon element has a compact mode.
virtual BOOL HasCompactMode() const;
TRUE if the ribbon element has a compact mode. FALSE otherwise.
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;
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.
Determines whether the ribbon element has a large mode.
virtual BOOL HasLargeMode() const;
TRUE if the ribbon element has a large mode. FALSE otherwise.
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;
Always returns FALSE.
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);
point
[in] This parameter is not used.
A pointer to the ribbon element if it exists; otherwise FALSE.
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;
Always returns TRUE.
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;
TRUE if the ribbon element image size is always large; otherwise FALSE.
Large image size is 32 x 32 pixels.
Indicates whether the ribbon element is in auto repeat mode.
virtual BOOL IsAutoRepeatMode(int& nDelay) const;
nDelay
[in] This parameter is not used.
Always returns FALSE.
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;
TRUE if the ribbon element is checked; otherwise FALSE.
Specifies whether the ribbon element is in a compact mode.
BOOL IsCompactMode() const;
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;
TRUE if the ribbon element is set to appear as a pop-up command; otherwise FALSE.
Specifies whether the ribbon element is disabled.
virtual BOOL IsDisabled() const;
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;
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;
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;
Always returns FALSE.
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;
TRUE if the ribbon element is highlighted; otherwise FALSE.
Indicates whether the current image for the ribbon element is intermediate size.
BOOL IsIntermediateMode() const;
TRUE if the image for the ribbon element is intermediate size; otherwise FALSE.
Intermediate image size is 16 x 16 pixels.
Indicates whether the current image for the ribbon element is large size.
BOOL IsLargeMode() const;
TRUE if the image for the ribbon element is large size; otherwise FALSE.
Large image size is 32 x 32 pixels.
Indicates whether the ribbon element is contained in a menu.
BOOL IsMenuMode() const;
TRUE if the ribbon element is contained in a menu; otherwise, FALSE.
Indicates whether the user has clicked the ribbon element.
virtual BOOL IsPressed() const;
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;
TRUE if the ribbon element is contained in the quick access toolbar; otherwise, FALSE.
Indicates whether the ribbon element is a display separator.
virtual BOOL IsSeparator() const;
TRUE if the ribbon element is a display separator; otherwise FALSE.
Indicates whether the ribbon element is contained in a group that displays a common border.
BOOL IsShowGroupBorder() const;
TRUE if the ribbon element is contained in a group that displays a common border; otherwise, FALSE.
Indicates whether the tooltip is displayed under the ribbon element.
virtual BOOL IsShowTooltipOnBottom() const;
TRUE if the tooltip is displayed under the ribbon element; FALSE if the tooltip is displayed near the pointer.
Indicates whether the ribbon element can be selected with the keyboard.
virtual BOOL IsTabStop() const;
Always returns TRUE.
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;
TRUE if the text for the ribbon element is displayed on the right; otherwise, FALSE.
Indicates whether the ribbon element is currently displayed.
BOOL IsVisible() const;
TRUE if the ribbon element is currently displayed; otherwise, FALSE.
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;
Always returns FALSE.
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);
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.
TRUE if the message was sent; otherwise, FALSE.
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);
nIndex
[in] The index of the ribbon element in the list.
Adds the ribbon element to the specified quick access toolbar.
virtual BOOL OnAddToQAToolbar(CMFCRibbonQuickAccessToolBar& qat);
qat
[in] The quick access toolbar.
Always returns TRUE indicating the ribbon element was added to the quick access toolbar.
Updates the tooltip for the ribbon element.
virtual void OnAfterChangeRect(CDC* pDC);
pDC
[in] This parameter is not used.
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();
Always returns FALSE.
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);
pDC
[in] This parameter is not used.
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);
pPanelMenuBar
[in] This parameter is not used.
pHot
[in] This parameter is not used.
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;
pDC
[in] A pointer to a device context.
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);
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.
Called by the framework when the menu image for the ribbon element is drawn.
virtual BOOL OnDrawMenuImage(
CDC* pDC,
CRect rect);
pDC
[in] Pointer to a device context.
rect
[in] Menu image rectangle.
Always returns TRUE to indicate the image was drawn.
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);
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.
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);
bIsMenuKey
[in] TRUE if the keytip displays a pop-up menu; otherwise, FALSE.
TRUE if the event was handled; otherwise FALSE.
Called by the framework when the user presses a menu keytip on the main panel.
virtual BOOL OnMenuKey(UINT nUpperChar);
nUpperChar
[in] This parameter is not used.
Always returns FALSE.
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);
nChar
[in] This parameter is not used.
Always returns FALSE.
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);
bIsRTL
[in] This parameter is not used.
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);
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);
bShow
[in] This parameter is not used.
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();
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);
uiCmdId
[in] The parameter is not used.
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();
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);
pParent
The parent window for the ribbon element.
data
The accessibility data for the ribbon element.
Always returns TRUE.
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);
bCompactMode
[in] TRUE to reduce the display size of the ribbon element; FALSE to increase the display size of the ribbon element.
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. |
Associates a data item with the ribbon element.
void SetData(DWORD_PTR dwData);
dwData
[in] The data value.
Sets the ribbon element to appear as a pop-up command.
void SetDefaultMenuLook(BOOL bIsDefaultMenuLook = TRUE);
bIsDefaultMenuLook
[in] TRUE to set the ribbon element to appear as a pop-up command; otherwise FALSE.
Sets the description for the ribbon element.
virtual void SetDescription(LPCTSTR lpszText);
lpszText
[in] The description for the ribbon element.
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);
nID
[in] The command ID.
Sets the initial display size for the ribbon element.
virtual void SetInitialMode(BOOL bOneRow = FALSE);
bOneRow
[in] TRUE to limit the display size for the ribbon element to compact or intermediate; otherwise, FALSE.
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);
lpszKeys
[in] The keytip for the ribbon element.
lpszMenuKeys
[in] 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);
pOriginal
[in] Pointer to a ribbon element.
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);
pParent
[in] Pointer to a ribbon category.
The tabbed groups in ribbon controls are called categories.
Sets the parent menu container for the ribbon element.
virtual void SetParentMenu(CMFCRibbonPanelMenuBar* pMenuBar);
pMenuBar
[in] The parent menu.
Sets the parent ribbon bar for the ribbon element.
virtual void SetParentRibbonBar(CMFCRibbonBar* pRibbonBar);
pRibbonBar
[in] Pointer to the parent ribbon bar.
Sets the dimensions of the display rectangle for the ribbon element.
void SetRect(CRect rect);
rect
[in] The dimensions of the rectangle.
Sets the text and keytip for the ribbon element.
virtual void SetText(LPCTSTR lpszText);
lpszText
[in] The text and keytip for the ribbon element.
To set the keytip for the ribbon element, append the newline escape sequence followed by the keytip characters to lpszText.
//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);
bSet
[in] TRUE to display the text on the right; otherwise FALSE.
Sets the tooltip text for the ribbon element.
virtual void SetToolTipText(LPCTSTR lpszText);
lpszText
[in] The tooltip text.
Sets the visibility of the ribbon element.
void SetVisible(BOOL bIsVisible);
bIsVisible
[in] TRUE to display the ribbon element; FALSE to hide the ribbon element.
Stretches the width of the ribbon element.
virtual void StretchHorizontally();
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);
pDC
[in] This parameter is not used.
nHeight
[in] The height of the row.
TRUE if the display height was set; otherwise, FALSE.
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();
Indicates whether the parent element has keyboard focus.
virtual BOOL HasFocus() const;
TRUE if the ribbon element is focused; otherwise FALSE.