CRibbon Class |
Description
CRibbon allows a ribbon to be added to a windows. Only Windows 7 (and above) supports the ribbon framework.
CRibbon Members
CRibbon | CRibbon();Constructs a CRibbon object. |
bool virtual CreateRibbon(CWnd* pWnd);Creates the ribbon
void virtual DestroyRibbon();Destroys the ribbon
IUIFramework* GetRibbonFramework() const;Returns the pointer to IUIFramwork, assigned when the ribbon is created.
UINT GetRibbonHeight() const;Returns the height of the ribbon.
IUnknown Methods
AddRef | STDMETHOD_(ULONG, AddRef());Increments the reference count for the interface on the object. |
Release | STDMETHOD_(ULONG, Release());Decrements the reference count for the interface on the object. |
QueryInterface | STDMETHOD(QueryInterface(REFIID iid, void** ppv));Retrieves pointers to the supported interfaces on the object. |
IUIApplication Methods
OnCreateUICommand | STDMETHOD(OnCreateUICommand)(UINT nCmdID, __in UI_COMMANDTYPE typeID, __deref_out IUICommandHandler** ppCommandHandler);Called by the Ribbon framework for each command specified in the Ribbon markup to bind the Command to an IUICommandHandler. |
OnDestroyUICommand | STDMETHOD(OnDestroyUICommand)(UINT32 commandId, __in UI_COMMANDTYPE typeID, __in_opt IUICommandHandler* commandHandler);Called for each Command specified in the Ribbon markup when the Ribbon host application window is destroyed. |
OnViewChanged | STDMETHOD(OnViewChanged)(UINT viewId, __in UI_VIEWTYPE typeId, __in IUnknown* pView, UI_VIEWVERB verb, INT uReasonCode);Called when the state of the Ribbon changes, for example, created, destroyed, or resized. |
IUICommandHandle methods
Execute | STDMETHODIMP Execute(UINT nCmdID, UI_EXECUTIONVERB verb, __in_opt const PROPERTYKEY* key, __in_opt const PROPVARIANT* ppropvarValue, __in_opt IUISimplePropertySet* pCommandExecutionProperties);Executes or previews the Commands bound to the Command handler. |
UpdateProperty | STDMETHODIMP UpdateProperty(UINT nCmdID, __in REFPROPERTYKEY key, __in_opt const PROPVARIANT* ppropvarCurrentValue, __out PROPVARIANT* ppropvarNewValue);Called by the Ribbon framework when a command property (PKEY) needs to be updated. |
Remarks
Microsoft's RibbonUI framework uses COM to implement the ribbon. The COM interfaces involved are IUIApplication and IUICommandHandler. The CRibbon class inherits from both IUIApplication and IUICommandHandler.
To create and interact with the ribbon, we override the relevant functions from both IUIApplication and IUICommandHandler.
The functions you may wish to override are:
- IUIApplication::OnCreateUICommand - Called for each Command specified in the Ribbon markup to bind the Command to an IUICommandHandler.
- IUIApplication::OnDestroyUICommand - Called for each Command specified in the Ribbon markup when the Ribbon host application window is destroyed.
- IUIApplication::OnViewChanged - Called when the state of a View changes.
- IUICommandHandler::Execute - Executes or previews the Commands bound to the Command handler.
- IUICommandHandler::UpdateProperty - Sets a property value for a bound Command, for example, setting a Command to enabled or disabled depending on the state of a View.
Refer to the RibbonSimple sample for a demonstration of how to add a ribbon to a simple window.
Summary Information
Header file | ribbon.h |
Win32/64 support | Yes |
WinCE support | No |
Library required | Comctl32.lib, Shlwapi.lib |