BinaryRibbonLivePreview

Live preview is the ribbon's most recognisable behaviour: the pointer rests on a style and the document takes it on; the pointer moves away and the document goes back; a click keeps it. Only the application knows what its document is and how to change it and change it back, so the ribbon does not do that part. A BinaryRibbonGallery says what the user is pointing at and when to stop, and the application does the rest.

The three events

Order

A request may follow another request, as the pointer moves from item to item, or follow a cancel; treat each as "show this item". A cancel is raised only while a preview is showing. A commit is raised for every selection a gallery makes, including one made from code or the keyboard with no preview before it, so treat it as "apply this item" whatever came first.

Where to listen

All three bubble, so a handler on the gallery hears that gallery alone and a handler on a tab, the ribbon or the window hears every gallery inside it. Attach handlers in code with the Add...Handler methods here, or in XAML with ribbon:BinaryRibbonLivePreview.PreviewRequested="OnPreviewRequested". A gallery raises nothing while its BinaryRibbonGallery.IsLivePreviewEnabled is false.

Previewing a table style on the table of an order form. Each thumbnail in the gallery carries the Style it stands for in its Tag.

private Style styleBeforePreview;

private void HookLivePreview()
{
    BinaryRibbonLivePreview.AddPreviewRequestedHandler(tableStyleGallery, (sender, e) =>
    {
        if (styleBeforePreview == null) styleBeforePreview = orderTable.Style;
        orderTable.Style = (Style)((FrameworkElement)e.Item).Tag;
    });

    BinaryRibbonLivePreview.AddPreviewCancelledHandler(tableStyleGallery, (sender, e) =>
    {
        if (styleBeforePreview != null) orderTable.Style = styleBeforePreview;
        styleBeforePreview = null;
    });

    BinaryRibbonLivePreview.AddPreviewCommittedHandler(tableStyleGallery, (sender, e) =>
    {
        orderTable.Style = (Style)((FrameworkElement)e.Item).Tag;
        styleBeforePreview = null;
        undoHistory.Record("Table style");
    });
}