BCGControlBar Pro for MFC
CBCGPRibbonBar

Detailed Description

The CBCGPRibbonBar class implements functionality of "Ribbon" control.

"Ribbon" control was introduced by Microsoft in Office 2007. It's not just a new control - it's a new user interface ideology. Ribbon control replaces traditional toolbars and menus with tabbed groups (Categories). Each group is logically split into Panels and each panel may contain various controls and command buttons. In addition, Ribbon control provides smart layout maximally utilizing the available space. For example, if a Panel has been stretched and has no place to display all available controls, it becomes a menu button which can display sub-items on a popup menu.

Ribbon control behaves as a "static" (non-floating) control bar and can be docked at the top of frame. In fact, the same Ribbon Bar can be used to implement Office 2007-style status bar or any other control that hosts Ribbon Categories (CBCGPRibbonCategory). A Ribbon Category is a logical entity. The visual representation of Category is a Ribbon Tab (CBCGPRibbonTab). A Category contains (and the Tab displays) a group of Ribbon Panels. Each Ribbon Panel contains one or more Ribbon Elements (CBCGPBaseRibbonElement - derived objects).

How to add ribbon control to your application:

Copy
// The simplest way to setup the Ribbon bar conent is using Ribbon Designer application: http://www.bcgsoft.com/doc/RibbonDesigner.htm
// Please read the steps below if you wish to create the bar dynamically in your code, not using the designer.
// Open MainFrm.h, remove CBCGPMenuBar m_wndMenuBar and CBCGPToolBar m_wndToolBar.
// Add definitions for the Ribbon Bar and Ribbon Main Button:
CBCGPRibbonBar m_wndRibbonBar;
CBCGPRibbonMainButton m_MainButton;
// Add definition for the panels image list:
CBCGPToolBarImages m_PanelIcons;
// Open MainFrm.cpp and remove everything related to m_wndMenuBar and m_wndToolBar.
//
// Add to the resources a bitmap for the Ribbon Main Button (IDB_MAIN). Use a bitmap 26x26 pixels.
// Add a bitmap for image list of small icons (16 pixels height, at 96 DPI) and a bitmap for image list of large icons (32 pixels height, at 96 DPI).
// Name them IDB_SMALL_ICONS and IDB_LARGE_ICONS respectively.
// Create Ribbon Bar in CMainFrame::OnCreate:
m_wndRibbonBar.Create(this);
// Initialize and set Main Ribbon Button:
m_MainButton.SetMenu(IDR_FILE_MENU);
m_MainButton.SetImage(IDB_MAIN);
m_MainButton.SetToolTipText(_T("File"));
m_wndRibbonBar.SetMainButton(&m_MainButton, CSize (45, 45));
// Initialize and load image list of panel icons:
m_PanelIcons.SetImageSize(CSize(16, 16));
m_PanelIcons.Load(IDB_PANEL_ICONS);
// Add the first category:
CBCGPRibbonCategory* pCategory = m_wndRibbonBar.AddCategory(
_T("&Write"), // Category name
IDB_WRITE, // Category small images (16 x 16)
IDB_WRITE_LARGE); // Category large images (32 x 32)
// Add the first Panel to category:
CBCGPRibbonPanel* pPanel = pCategory->AddPanel(
_T("Clipboard"), // Panel name
m_PanelIcons.ExtractIcon (0)); // Panel icon
// Now, we need to add ribbon elements (buttons) to the panel:
// Create the first button to Panel ("Paste"):
CBCGPRibbonButton* pPasteButton = new CBCGPRibbonButton (ID_EDIT_PASTE, _T("Paste"), -1, 0);
// The third parameter (-1) tells that this button does not have a small icon.
// Therefore the "Paste" button will be always displayed with large icon.
// Associate a popup menu with the "Paste" button:
pPasteButton->SetMenu (IDR_CONTEXT_MENU);
// Add other buttons to the panel. These buttons have small icons only:
pPanel->Add (new CBCGPRibbonButton (ID_EDIT_CUT, _T("Cut"), 1));
pPanel->Add (new CBCGPRibbonButton (ID_EDIT_COPY, _T("Copy"), 2));
pPanel->Add (new CBCGPRibbonButton (ID_EDIT_PAINT, _T("Paint"), 9));
+ Inheritance diagram for CBCGPRibbonBar:

Public Member Functions

 CBCGPRibbonBarConstructor.
 
 ActivateContextCategoryActivates context category.
 
 AddBackstageCategoryAdds backstage category.
 
 AddCaptionCustomButtonAdds a custom caption button.
 
 AddCategoryAdds a new category to ribbon control.
 
 AddContextCategoryAdds a context category.
 
 AddMainCategoryCreates main ribbon panel.
 
 AddToTabsAdds a ribbon element at the right side of ribbon control.
 
 CreateCreates the Windows control and attaches it to CBCGPRibbonBar.
 
 DoOpenPinnedFileCalled by the framework when user clicks on the pinned file in the recent files list.
 
 EnableBackstagePageCaptionsEnables the backstage view page captions.
 
 EnableCommandSearchEnables the Ribbon command search.
 
 EnableCustomizationEnables the Ribbon bar customization.
 
 EnableKeyTipsEnables or disables key tips feature for the Ribbon control.
 
 EnableMinimizeButtonShows or hides a minimize button.
 
 EnablePrintPreviewAllows to display the "Print Preview" tab
 
 EnableStartPageEnables the start page.
 
 EnableToolTipsEnables or disables tooltips on the ribbon control.
 
 FindByDataFinds a ribbon element by associated user-defined data.
 
 FindByIDFinds a ribbon element by its command ID.
 
 FindCategoryIndexByDataReturns category index by user-defined data associated with category.
 
 ForceRecalcLayoutAdjusts the layout of the Ribbon bar controls.
 
 GetActiveCategoryReturns a pointer to active category.
 
 GetApplicationModesGets currently selected application modes.
 
 GetBackgroundImageGets the Ribbon background image.
 
 GetBackstageCategoryRetrieves a pointer to backstage category.
 
 GetBackstagePageTransitionEffectGets backstage page transition effect.
 
 GetBackstagePageTransitionTimeGets backstage page transition time.
 
 GetCaptionButtonIconStyleReturns caption button icon style.
 
 GetCaptionCustomButtonRetrivies a custom caption button by index.
 
 GetCaptionCustomButtonsCountReturns custom caption buttons count.
 
 GetCategoryReturns a category located at the specified index.
 
 GetCategoryCountReturns a number of categories in ribbon bar.
 
 GetCategoryIndexReturns category index.
 
 GetCommandSearchOptionsGets the command search ("Tell me") options.
 
 GetContextNameRetrieves context name.
 
 GetCustomizationOptionsGets Ribbon bar customization options.
 
 GetDefaultBackstagePageGets default backstage page.
 
 GetDefaultHeightReturns a default (recommended) Ribbon Bar height. Should be used in the dialog mode only
 
 GetElementsByIDReturns an array of all elements with specified ID.
 
 GetImagesLuminosityGets Ribbon images luminosity.
 
 GetKeyTipsDelayReturns key tips delay.
 
 GetMainButtonProvides access to main ribbon button.
 
 GetMainCategoryProvides access to main ribbon category.
 
 GetQuickAccessCommandsRetrieves the list of commands whose elements are located on Quick Access Toolbar.
 
 GetVisibleElementsGets visible elements.
 
 HasBackstagePageCaptionsTells whether backstage pages have captions.
 
 HasMinimizeButtonTells whether minimize button is displayed or hidden.
 
 HideAllContextCategoriesHides all context categories.
 
 HitTestReturns a pointer to a ribbon element located at the specified point.
 
 IsAutoHideModeAvailableTells whether the Ribbon bar auto-hide mode is available in the current visual theme.
 
 IsAutoStartPageCheck whether a start page is automatically displayed on application startup.
 
 IsBackstageModeTells whether backstage mode is turned on or off.
 
 IsBackstageViewActiveTells whether backstage view is currently active, or not.
 
 IsCommandSearchEnabledTells whether the a command search is enabled.
 
 IsCustomizationEnabledTells whether a Ribbon bar customization is enabled.
 
 IsDefaultSystemMenuTells whether the default system menu is used instead of the themed menu.
 
 IsDialogModeTells whether the Ribbon Bar was crated as child of the dialog box or property page.
 
 IsGrayDisabledImagesTells whether the Ribbon disabled images should be grayed or not.
 
 IsInAutoHideModeTells whether the Ribbon bar is in auto-hide mode.
 
 IsKeyTipEnabledTells whether the key tips feature is enabled, or not.
 
 IsMinimizedTells whether the Ribbon bar is minimized or not.
 
 IsPrintPreviewEnabledTells whether the library-defined "Print Preview" tab is allowed.
 
 IsQuickAccessToolbarOnTopTells whether Quick Access Toolbar is located on the top, or on the bottom of ribbon control.
 
 IsReplaceFrameCaptionTells whether ribbon control replaces main frame caption, or is located under the frame caption.
 
 IsScenicLookTells whether the current look of Ribbon is scenic or regular.
 
 IsStartPageEnabledTells whether a start page is enabled.
 
 IsToolTipDescrEnabledTells whether tooltip descriptions are enabled or disabled.
 
 IsToolTipEnabledTells whether tooltips are enabled or disabled for the ribbon control.
 
 LoadFromBufferLoads a Ribbon Bar schema from a memory buffer containing XML definition of the schema.
 
 LoadFromVSRibbonLoads a Ribbon Bar schema from Visual Studio Ribbon resource.
 
 LoadFromVSRibbonLoads a Ribbon Bar schema from Visual Studio Ribbon resource.
 
 LoadFromXMLLoads a Ribbon Bar schema from XML.
 
 LoadFromXMLLoads a Ribbon Bar schema from XML.
 
 OnFilterSearchResultCalled before a search result is added to the list of results.
 
 RecalcLayoutRe-calculates the Ribbon bar layout.
 
 RemoveAllCaptionCustomButtonsRemoves all custom caption buttons.
 
 RemoveAllCategoriesRemoves all categories.
 
 RemoveAllFromTabsRemoves all ribbon elements from tab area.
 
 RemoveCategoryRemoves a category located at the specified index,
 
 ReplaceRibbonElementByIDReplaces ribbon controls that have a specific identifier with a new control.
 
 SetActiveCategoryActivates the specified category.
 
 SetApplicationModesSets Ribbon application modes.
 
 SetAutoHideModeEnables or disables the Ribbon bar auto-hide mode.
 
 SetBackgroundImageSets the Ribbon bar's background image
 
 SetBackgroundImageSets the Ribbon bar's background image
 
 SetBackstageModeTurns backstage mode on or off.
 
 SetBackstagePageTransitionEffectSets backstage page transition effect.
 
 SetCaptionButtonIconStyleSpecifies a Ribbon caption button icon style.
 
 SetCommandSearchOptionsSpecifies the command search ("Tell me") options.
 
 SetDefaultBackstagePageSets default backstage page.
 
 SetDefaultSystemMenuSpecifies the Ribbon system menu style.
 
 SetElementKeysSets the specified key tips for all Ribbon's elements with specified command ID.
 
 SetGrayDisabledImagesSpecifies whether the Ribbon disabled images should be grayed or not.
 
 SetImagesLuminositySpecifies the Ribbon images luminosity.
 
 SetMainButtonSets main ribbon button.
 
 SetQuickAccessCommandsPlaces ribbon elements on Quick Access Toolbar.
 
 SetQuickAccessDefaultStateSets the current QAT state.
 
 SetQuickAccessToolbarOnTopRelocates Quick Access Toolbar on the top, or on the bottom of ribbon control.
 
 SetScenicLookSets or unsets scenic look for Ribbon Bar.
 
 SetTabButtonIconsSets icons for the buttons located on the same row as tabs (on the right side).
 
 ShowBackstagePrintViewActivates backstage "Print" page.
 
 ShowBackstageRecentViewActivates backstage "Recent" page.
 
 ShowBackstageViewActivates a backstage page.
 
 ShowBackstageViewActivates a backstage page.
 
 ShowCategoryShows or hides category.
 
 ShowContextCategoriesShows or hides context categories with specified context ID.
 
 ShowStartPageActivates a start page.
 
 ToggleMinimizeStateToggles minimized and normal Ribbon control state.
 
- Public Member Functions inherited from CBCGPControlBar
 AdjustSizeImmediateImmediately recalculates layout of a control bar.
 
 CalcInsideRectCalculates the inside rectangle of a control bar taking into account the borders and grippers.
 
 CanBeDockedDetermines whether a control bar can be docked at the specified dock bar.
 
 CanBeTabbedDocumentTells whether control bar can be converted to tabbed document.
 
 CreateCreates the Windows control bar and attaches it to the CBCGPControlBar object.
 
 CreateDefaultMiniframeCreates a mini-frame window for a control bar when it's being floated.
 
 CreateExCreates the Windows control bar and attaches it to the CBCGPControlBar object.
 
 DockControlBarDocks the control bar to a dock bar.
 
 DoesAllowSiblingBarsIndicates whether it is possible to dock another control bar at the same row where this control bar is docked.
 
 FloatControlBarMakes the control bar floating.
 
 GetBordersReturns the width of the control bar borders.
 
 GetExclusiveRowModeTells whether the control bar is in exclusive row mode or not.
 
 OnAfterChangeParentCalled by the framework when the parent of a control bar has changed.
 
 OnAfterFloatCalled by the framework when a control bar has floated.
 
 OnBeforeChangeParentCalled by the framework when the parent of the control bar is about to be changed as a result of docking or floating operation.
 
 OnBeforeFloatCalled by the framework when a control bar is about to float.
 
 OnPressCloseButtonCalled by the framework when user presses the close button on control bar's caption.
 
 OnShowControlBarMenuCalled by the framework when a special control bar menu is about to be displayed.
 
 SetBordersSets the border values of the control bar.
 
 SetBordersSets the border values of the control bar.
 
 SetExclusiveRowModeEnables or disables the exclusive row mode.
 
 SetMiniFrameRTCSets the runtime class information about the default mini-frame window.
 
 ToggleAutoHideToggles autohide mode.
 
- Public Member Functions inherited from CBCGPBaseControlBar
 AddControlBarAdds a control bar to docking manager.
 
 AdjustDockingLayoutRedirects a call to docking manager to adjust docking layout.
 
 AdjustLayoutCalled by the framework when a control bar should adjust its internal layout according to a new size or position.
 
 CanAcceptBarDetermines whether another control bar can be docked to this control bar.
 
 CanAutoHideDetermines whether the control bar can be switched to autohide mode.
 
 CanBeAttachedCalled by the framework to determine if the control bar can be docked to another control bar or frame window.
 
 CanBeClosedDetermines whether the control bar may be hidden.
 
 CanBeResizedDetermines whether this control bar can be resized.
 
 CanFloatDetermines whether the control bar can float.
 
 CanFocusSpecifies whether a control bar can receive focus.
 
 CreateExCreates a Windows control.
 
 DoesAllowDynInsertBeforeDetermines whether it is possible to dynamically insert a control bar before this control bar.
 
 EnableDockingEnables docking to the main frame.
 
 EnableGripperEnables/disables the control caption (gripper).
 
 GetBarIconReturns control bar icon.
 
 GetBarStyleReturns the control bar style.
 
 GetBCGStyleReturns the library specific control bar styles.
 
 GetCurrentAlignmentReturns the current control bar alignment.
 
 GetDockModeReturns the current dock mode for the control bar.
 
 GetDockRowReturns a pointer to a dock bar row.
 
 GetDockSiteReturns a pointer to dock site.
 
 GetEnabledAlignmentReturns the enabled alignment.
 
 GetParentMiniFrameReturns a pointer to the parent mini-frame window.
 
 GetParentTabWndRetrieves a pointer to the parent tabbed window.
 
 IsDockedDetermines whether the control bar is docked or not.
 
 IsHorizontalDetermines whether the control bar is docked horizontally.
 
 IsMDITabbedTells whether control bar is placed on MDI child window as tabbed document.
 
 IsVisibleDetermines whether a control bar is visible or not.
 
 OnRemoveFromMiniFrameCalled by the framework when a control bar is being removed from its parent mini-frame window.
 
 SetBarAlignmentSets the current alignment for a control bar.
 
 SetBarStyleSets a control bar style
 
 SetDockModeSets a new docking method for a control bar.
 
 ShowControlBarShows or hides a control bar.
 
- Public Member Functions inherited from CBCGPWnd
 IsOnGlassChecks if window is located on DWM ("Glass") area of the parent window.
 
 IsVisualManagerStyleTells whether a window uses visual manager style.
 

Additional Inherited Members

- Public Attributes inherited from CBCGPControlBar
 m_recentDockInfoContains the recent docking information.
 
- Static Public Attributes inherited from CBCGPControlBar
 m_bHandleMinSizeEnables consistent handling of minimal size.
 
- Protected Member Functions inherited from CBCGPControlBar
 OnAfterDockCalled by the framework when a control bar has been docked.
 
 OnBeforeDockCalled by the framework when the control bar is about to be docked.
 
- Protected Member Functions inherited from CBCGPBaseControlBar
 DoPaintPaints the control bar.
 
- Protected Member Functions inherited from CBCGPGestureBase
 OnGestureEventBeginCalled by the framework to handle BCGP_GID_BEGIN notification.
 
 OnGestureEventEndCalled by the framework to handle BCGP_GID_END notification.
 
 OnGestureEventPanCalled by the framework to handle BCGP_GID_PAN notification
 
 OnGestureEventPressAndTapCalled by the framework to handle BCGP_GID_PRESSANDTAP notification.
 
 OnGestureEventRotateCalled by the framework to handle BCGP_GID_ROTATE notification.
 
 OnGestureEventTwoFingerTapCalled by the framework to handle BCGP_GID_TWOFINGERTAP notification.
 
 OnGestureEventZoomCalled by the framework to handle BCGP_GID_ZOOM notification.
 
 ProcessGestureEventThis method should be called from WM_GESTURE message handler.