WPF › Ribbon › BinaryRibbonDropDownButton

BinaryRibbonDropDownButton

class.NET 6 / 8 / 10.NET Framework 4.8Binarymission.WPF.Controls.Office

A ribbon button that opens a drop-down of further commands – Office's Paste Special, Insert Table or Export menus.

public class BinaryRibbonDropDownButton : MenuItem, IBinaryRibbonComponent, IBinaryRibbonContentElementBoundsConfigurable, ICommandSource, IBinaryRibbonKeyTipControl

Inherits from / implements: MenuItem, IBinaryRibbonComponent, IBinaryRibbonContentElementBoundsConfigurable, ICommandSource, IBinaryRibbonKeyTipControl

Remarks

Use it where one picture on the ribbon stands for several related commands. A click on the button opens the drop-down and a second click closes it; nothing is run until the user chooses an entry. To run a default command on click and keep the list for the alternatives, use BinaryRibbonSplitButtonControl instead.

The drop-down

The entries are the button's ItemsControl.Items – usually BinaryRibbonMenuItem controls, handled through their MenuItem.Click or MenuItem.Command. They are stacked vertically and scroll when they do not fit. Every entry is used as it stands, so give the drop-down controls, not data objects. DropDownHeaderContent and DropDownFooterContent add content above and below the entries, and a drop-down with no entries shows only those – which is how a colour picker or any other panel of your own is put under a ribbon button.

A click on an entry – any menu item or button in the drop-down – closes it. Opening a drop-down closes any other ribbon drop-down that is open, unless this one is inside it.

Pictures, caption and size

The caption is Content, not HeaderedItemsControl.Header. Large, the button shows LargeImage over the caption and an arrow; medium, SmallImage (or the large picture scaled down) beside the caption and an arrow; small, the picture and arrow alone. The size is set by the BinaryRibbonGroup holding it, through the attached BinaryRibbonBarPanel.SizeProperty.

Keyboard

Enter or Space opens the drop-down and Escape closes it. A key tip (BinaryKeyTip.AccessKeyProperty) opens or closes it.

Examples

An Export button with three formats and a footer link.

<ribbon:BinaryRibbonGroup TitleText="Share"
        xmlns:ribbon="clr-namespace:Binarymission.WPF.Controls.Office;assembly=Binarymission.WPF.Controls.BinaryRibbon">
    <ribbon:BinaryRibbonDropDownButton Content="Export"
                                       LargeImage="Images/Export32.png"
                                       SmallImage="Images/Export16.png"
                                       DropDownWidth="220"
                                       ribbon:BinaryKeyTip.AccessKey="E"
                                       PopupClose="OnExportMenuClosed">
        <ribbon:BinaryRibbonMenuItem Header="PDF document"   Image="Images/Pdf16.png"   Click="OnExportPdf" />
        <ribbon:BinaryRibbonMenuItem Header="Excel workbook" Image="Images/Excel16.png" Click="OnExportExcel" />
        <ribbon:BinaryRibbonMenuItem Header="CSV file"       Image="Images/Csv16.png"   Click="OnExportCsv" />
        <ribbon:BinaryRibbonDropDownButton.DropDownFooterContent>
            <TextBlock Margin="8,4"><Hyperlink Click="OnExportSettings">Export settings...</Hyperlink></TextBlock>
        </ribbon:BinaryRibbonDropDownButton.DropDownFooterContent>
    </ribbon:BinaryRibbonDropDownButton>
</ribbon:BinaryRibbonGroup>

Members at a glance

Constructors
`BinaryRibbonDropDownButton`	Creates a drop-down button with no caption, pictures or entries.
Properties
`BinaryRibbonTag`	Gets or sets any object of your own to keep with the button.
`Content`	Gets or sets the button's caption – "Export", "Insert Table".
`CornerRadius`	Gets or sets how rounded the corners of the button's frame and highlight are.
`DropDownFooterContent`	Gets or sets content shown at the foot of the drop-down, under the entries – a "More options..." link, a hint, a total.
`DropDownFooterDataTemplate`	Gets or sets the template that draws `DropDownFooterContent` when it is a data object rather than a UI element.
`DropDownHeaderContent`	Gets or sets content shown at the top of the drop-down, above the entries – a heading, a search box, or a whole panel of your own.
`DropDownHeaderDataTemplate`	Gets or sets the template that draws `DropDownHeaderContent` when it is a data object rather than a UI element.
`DropDownWidth`	Gets or sets the width of the drop-down.
`IsDropDownCurrentlyPressed`	Gets or sets whether the drop-down is open.
`LargeImage`	Gets or sets the picture the button shows when the ribbon draws it large.
`MaximumDropDownPanelHeight`	Gets or sets the tallest the drop-down may grow before its entries scroll.
`PopupAnimation`	Gets or sets how the drop-down appears.
`PopupPlacement`	Gets or sets where the drop-down opens, relative to the button.
`ShowDropDownImage`	Gets or sets whether the button shows the small arrow that says it opens a drop-down.
`SmallImage`	Gets or sets the picture the button shows when the ribbon draws it medium or small.
Methods
`ForcePopupActiveOnMouseUp`	Holds the drop-down open through the release of the mouse button that opened it, which would otherwise count as a click outside and close it at once.
`ForcePopupInactive`	Lets the drop-down close again on the next click outside it, ending the hold put on it by `ForcePopupActiveOnMouseUp`.
`GetContainerForItemOverride`	Creates a container for an entry: a `BinaryRibbonMenuItem`.
`IsItemItsOwnContainerOverride`	Reports whether an entry is shown as it stands, which for this control is always.
`OnApplyTemplate`	Finds the `PART_Popup` pop-up in the new template and starts listening for it opening and closing, then applies the template as the base class does.
`OnDropDownCurrrentlyPressedChanged`	Called when `IsDropDownCurrentlyPressed` changes; opens or closes the drop-down to match.
`OnKeyDown`	Opens the drop-down on Enter or Space and closes it on Escape, after the base handling of the key.
`OnMouseLeftButtonDown`	Opens or closes the drop-down when the press lands on the button itself, then passes the press to the base class.
`OnMouseLeftButtonUp`	Handles the release of the press that opened the drop-down, so that it does not close it again straight away.
`OnPopupClose`	Called when the drop-down closes; releases the button and raises `PopupClose`.
`OnPopupOpen`	Called when the drop-down opens; marks the button pressed and raises `PopupOpen`.
`SwitchState`	Opens the drop-down if it is closed and closes it if it is open – what a click on the button and its key tip do.
Events
`PopupClose`	Occurs when the drop-down has closed, whether an entry was chosen or the user clicked elsewhere.
`PopupOpen`	Occurs when the drop-down has opened.
Fields
`ContentProperty`	Identifies the `Content` dependency property.
`CornerRadiusProperty`	Identifies the `CornerRadius` dependency property.
`DropDownFooterContentProperty`	Identifies the `DropDownFooterContent` dependency property.
`DropDownFooterDataTemplateProperty`	Identifies the `DropDownFooterDataTemplate` dependency property.
`DropDownHeaderContentProperty`	Identifies the `DropDownHeaderContent` dependency property.
`DropDownHeaderDataTemplateProperty`	Identifies the `DropDownHeaderDataTemplate` dependency property.
`DropDownWidthProperty`	Identifies the `DropDownWidth` dependency property.
`IsDropDownCurrentlyPressedProperty`	Identifies the `IsDropDownCurrentlyPressed` dependency property.
`LargeImageProperty`	Identifies the `LargeImage` dependency property.
`MaximumDropDownPanelHeightProperty`	Identifies the `MaximumDropDownPanelHeight` dependency property.
`PopupAnimationProperty`	Identifies the `PopupAnimation` dependency property.
`PopupCloseEvent`	Identifies the `PopupClose` routed event.
`PopupOpenEvent`	Identifies the `PopupOpen` routed event.
`PopupPlacementProperty`	Identifies the `PopupPlacement` dependency property.
`ShowDropDownImageProperty`	Identifies the `ShowDropDownImage` dependency property.
`SmallImageProperty`	Identifies the `SmallImage` dependency property.
`popup`	The pop-up that holds the drop-down – the template part named `PART_Popup`.

Constructors

BinaryRibbonDropDownButton

public BinaryRibbonDropDownButton()

Creates a drop-down button with no caption, pictures or entries.

Remarks

The button listens for MenuItem.Click and Click bubbling up from its entries, and closes the drop-down when either arrives.

Properties

BinaryRibbonTag

public object BinaryRibbonTag

Gets or sets any object of your own to keep with the button.

Value: Any object. The default is null.

Remarks

The ribbon never reads it. It is a plain property, not a dependency property, so it cannot be the target of a binding or a style setter; use FrameworkElement.Tag for that.

Content

public object Content

Gets or sets the button's caption – "Export", "Insert Table".

Value: Any content; usually a string. The default is null.

Remarks

This is the caption on the ribbon. HeaderedItemsControl.Header, inherited from MenuItem, is not shown. The caption is hidden when the button is drawn small.

CornerRadius

public CornerRadius CornerRadius

Gets or sets how rounded the corners of the button's frame and highlight are.

Value: The radius of each corner, in device-independent units (1/96 inch). The default is 3 on every corner.

Remarks

Inside a BinaryRibbonButtonGroup the group sets this itself, so a value set on the button there is replaced.

DropDownFooterContent

public object DropDownFooterContent

Gets or sets content shown at the foot of the drop-down, under the entries – a "More options..." link, a hint, a total.

Value: Any content: a UI element, or an object drawn by DropDownFooterDataTemplate. The default is null, which shows nothing.

DropDownFooterDataTemplate

public DataTemplate DropDownFooterDataTemplate

Gets or sets the template that draws DropDownFooterContent when it is a data object rather than a UI element.

Value: The template. The default is null, which shows a data object as its text.

DropDownHeaderContent

public object DropDownHeaderContent

Gets or sets content shown at the top of the drop-down, above the entries – a heading, a search box, or a whole panel of your own.

Value: Any content: a UI element, or an object drawn by DropDownHeaderDataTemplate. The default is null, which shows nothing.

Remarks

A drop-down button with no entries shows only its header and footer, so this is where to put a picker or panel that is not a list of commands.

DropDownHeaderDataTemplate

public DataTemplate DropDownHeaderDataTemplate

Gets or sets the template that draws DropDownHeaderContent when it is a data object rather than a UI element.

Value: The template. The default is null, which shows a data object as its text.

DropDownWidth

public double DropDownWidth

Gets or sets the width of the drop-down.

Value: The width in device-independent units (1/96 inch). The default is NaN, which sizes the drop-down to its widest entry.

IsDropDownCurrentlyPressed

public bool IsDropDownCurrentlyPressed

Gets or sets whether the drop-down is open.

Value: true while the drop-down is open. The default is false.

Remarks

Set it to open or close the drop-down from code; a click on the button flips it. Setting it to true closes any other ribbon drop-down that is open, unless this one is inside it.

The control sets it back to false when the drop-down closes for any reason, so a two-way binding stays in step.

Example

// Open the Export drop-down when the user presses Ctrl+E.
exportButton.IsDropDownCurrentlyPressed = true;

LargeImage

public ImageSource LargeImage

Gets or sets the picture the button shows when the ribbon draws it large.

Value: The picture, drawn 32 x 32 device-independent units. The default is null.

MaximumDropDownPanelHeight

public double MaximumDropDownPanelHeight

Gets or sets the tallest the drop-down may grow before its entries scroll.

Value: The height in device-independent units (1/96 inch). The default is NaN, which sets no limit.

Remarks

The header and footer content stay in view; only the entries between them scroll.

PopupAnimation

public PopupAnimation PopupAnimation

Gets or sets how the drop-down appears.

Value: The animation. The default is Fade.

PopupPlacement

public PlacementMode PopupPlacement

Gets or sets where the drop-down opens, relative to the button.

Value: The placement. The default is Bottom: below the button, left edges aligned.

Remarks

It applies while the button is drawn medium or small. A large button always opens its drop-down below it.

ShowDropDownImage

public bool ShowDropDownImage

Gets or sets whether the button shows the small arrow that says it opens a drop-down.

Value: true to show the arrow. The default is true.

Remarks

Turn it off for a button whose picture already says it opens something – a colour swatch, say – or where the arrow would not fit.

SmallImage

public ImageSource SmallImage

Gets or sets the picture the button shows when the ribbon draws it medium or small.

Value: The picture, drawn 16 x 16 device-independent units. The default is null, which shows LargeImage scaled down instead.

Methods

ForcePopupActiveOnMouseUp

protected void ForcePopupActiveOnMouseUp()

Holds the drop-down open through the release of the mouse button that opened it, which would otherwise count as a click outside and close it at once.

Remarks

Pair it with ForcePopupInactive on the release.

ForcePopupInactive

protected void ForcePopupInactive()

Lets the drop-down close again on the next click outside it, ending the hold put on it by ForcePopupActiveOnMouseUp.

GetContainerForItemOverride

protected override DependencyObject GetContainerForItemOverride()

Creates a container for an entry: a BinaryRibbonMenuItem.

Returns

A new BinaryRibbonMenuItem.

Remarks

Not called by this control, because IsItemItsOwnContainerOverride says that every entry is its own container. A derived class that overrides that method can use this one.

IsItemItsOwnContainerOverride

protected override bool IsItemItsOwnContainerOverride(object item)

Reports whether an entry is shown as it stands, which for this control is always.

Parameters

item: The entry.

Returns

Always true.

Remarks

Every entry is placed in the drop-down as it is, so the entries must be UI elements; GetContainerForItemOverride is never called.

OnApplyTemplate

public override void OnApplyTemplate()

Finds the PART_Popup pop-up in the new template and starts listening for it opening and closing, then applies the template as the base class does.

OnDropDownCurrrentlyPressedChanged

protected virtual void OnDropDownCurrrentlyPressedChanged(bool oldValue, bool newValue)

Called when IsDropDownCurrentlyPressed changes; opens or closes the drop-down to match.

Parameters

oldValue: The value before the change.
newValue: The value after it: true to open.

Remarks

The name is spelled with three r's and is kept that way so that existing overrides still compile. Call the base method from an override, or the drop-down stops following the property.

OnKeyDown

protected override void OnKeyDown(KeyEventArgs e)

Opens the drop-down on Enter or Space and closes it on Escape, after the base handling of the key.

Parameters

e: The data for the event.

OnMouseLeftButtonDown

protected override void OnMouseLeftButtonDown(MouseButtonEventArgs e)

Opens or closes the drop-down when the press lands on the button itself, then passes the press to the base class.

Parameters

e: The data for the event.

Remarks

A press inside the open drop-down is not on the button, so it reaches the entry under it.

OnMouseLeftButtonUp

protected override void OnMouseLeftButtonUp(MouseButtonEventArgs e)

Handles the release of the press that opened the drop-down, so that it does not close it again straight away.

Parameters

e: The data for the event.

OnPopupClose

protected virtual void OnPopupClose(object sender, EventArgs e)

Called when the drop-down closes; releases the button and raises PopupClose.

Parameters

sender: The pop-up that closed.
e: Not used.

Remarks

Override it to react to the drop-down closing; call the base method so that the button is released and the event is still raised.

OnPopupOpen

protected virtual void OnPopupOpen(object sender, EventArgs e)

Called when the drop-down opens; marks the button pressed and raises PopupOpen.

Parameters

sender: The pop-up that opened.
e: Not used.

Remarks

Override it to react to the drop-down opening without attaching to the pop-up yourself; call the base method so that the button stays in step and the event is still raised.

SwitchState

protected virtual void SwitchState()

Opens the drop-down if it is closed and closes it if it is open – what a click on the button and its key tip do.

Remarks

BinaryRibbonSplitButtonControl overrides it to do nothing, so that a click on its main part runs the command instead.

Events

PopupClose

public event RoutedEventHandler PopupClose

Occurs when the drop-down has closed, whether an entry was chosen or the user clicked elsewhere.

Remarks

A bubbling routed event, raised once the drop-down is gone.

PopupOpen

public event RoutedEventHandler PopupOpen

Occurs when the drop-down has opened.

Remarks

A bubbling routed event, so one handler on a group, a tab or the window hears it from every drop-down button inside. Handle it to fill the drop-down at the last moment – a list of recent files, say.

Fields

ContentProperty static

public static readonly DependencyProperty ContentProperty

Identifies the Content dependency property.

CornerRadiusProperty static

public static readonly DependencyProperty CornerRadiusProperty

Identifies the CornerRadius dependency property.

DropDownFooterContentProperty static

public static readonly DependencyProperty DropDownFooterContentProperty

Identifies the DropDownFooterContent dependency property.

DropDownFooterDataTemplateProperty static

public static readonly DependencyProperty DropDownFooterDataTemplateProperty

Identifies the DropDownFooterDataTemplate dependency property.

DropDownHeaderContentProperty static

public static readonly DependencyProperty DropDownHeaderContentProperty

Identifies the DropDownHeaderContent dependency property.

DropDownHeaderDataTemplateProperty static

public static readonly DependencyProperty DropDownHeaderDataTemplateProperty

Identifies the DropDownHeaderDataTemplate dependency property.

DropDownWidthProperty static

public static readonly DependencyProperty DropDownWidthProperty

Identifies the DropDownWidth dependency property.

IsDropDownCurrentlyPressedProperty static

public static readonly DependencyProperty IsDropDownCurrentlyPressedProperty

Identifies the IsDropDownCurrentlyPressed dependency property.

LargeImageProperty static

public static readonly DependencyProperty LargeImageProperty

Identifies the LargeImage dependency property.

MaximumDropDownPanelHeightProperty static

public static readonly DependencyProperty MaximumDropDownPanelHeightProperty

Identifies the MaximumDropDownPanelHeight dependency property.

PopupAnimationProperty static

public static readonly DependencyProperty PopupAnimationProperty

Identifies the PopupAnimation dependency property.

PopupCloseEvent static

public static readonly RoutedEvent PopupCloseEvent

Identifies the PopupClose routed event.

PopupOpenEvent static

public static readonly RoutedEvent PopupOpenEvent

Identifies the PopupOpen routed event.

PopupPlacementProperty static

public static readonly DependencyProperty PopupPlacementProperty

Identifies the PopupPlacement dependency property.

ShowDropDownImageProperty static

public static readonly DependencyProperty ShowDropDownImageProperty

Identifies the ShowDropDownImage dependency property.

SmallImageProperty static

public static readonly DependencyProperty SmallImageProperty

Identifies the SmallImage dependency property.

BinaryRibbonDropDownButton

Remarks

The drop-down

Pictures, caption and size

Keyboard

Examples

See also

Members at a glance

Constructors

BinaryRibbonDropDownButton

Remarks

Properties

BinaryRibbonTag

Remarks

Content

Remarks

CornerRadius

Remarks

DropDownFooterContent

See also

DropDownFooterDataTemplate

DropDownHeaderContent

Remarks

See also

DropDownHeaderDataTemplate

DropDownWidth

IsDropDownCurrentlyPressed

Remarks

Example

LargeImage

See also

MaximumDropDownPanelHeight

Remarks

PopupAnimation

PopupPlacement

Remarks

ShowDropDownImage

Remarks

SmallImage

See also

Methods

ForcePopupActiveOnMouseUp

Remarks

ForcePopupInactive

GetContainerForItemOverride

Returns

Remarks

IsItemItsOwnContainerOverride

Parameters

Returns

Remarks

OnApplyTemplate

OnDropDownCurrrentlyPressedChanged

Parameters

Remarks

OnKeyDown

Parameters

OnMouseLeftButtonDown

Parameters

Remarks

OnMouseLeftButtonUp

Parameters

OnPopupClose

Parameters

Remarks

OnPopupOpen

Parameters

Remarks

SwitchState

Remarks

Events

PopupClose

Remarks

See also

PopupOpen

Remarks

See also

Fields

ContentProperty static

CornerRadiusProperty static