HypernovaDesktop Components · docs
Binarymission
WPF › Ribbon › BinaryRibbonGroup

BinaryRibbonGroup

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

A titled group of related commands on a ribbon tab – Clipboard, Font, Paragraph – with an optional dialog launcher in its corner, which folds into a single drop-down button when the ribbon runs out of room.

public class BinaryRibbonGroup : Control, IBinaryRibbonComponentCanRenderInReducedSizeState, IBinaryRibbonComponentCanDisplayImage, IBinaryRibbonKeyTipControl

Inherits from / implements: Control, IBinaryRibbonComponentCanRenderInReducedSizeState, IBinaryRibbonComponentCanDisplayImage, IBinaryRibbonKeyTipControl

Remarks

Commands

The group's content is Controls. Ribbon commands – BinaryRibbonButton, BinaryRibbonSplitButtonControl, BinaryRibbonComboBox, BinaryRibbonGallery and the others – are sized by the group; anything else is laid out as it is. Large commands take the full height of the group; medium and small ones stack three to a column. TitleText is drawn underneath.

Giving way

When the window narrows, the ribbon takes the groups of the selected tab down a step at a time, from the last group back (ResizingDepth): large commands become medium and then small, galleries show fewer columns, and at the last step the group folds into one button (IsMinimized) showing its Image and title, whose drop-down holds the commands at full size. Each command's steps can be set with BinaryRibbonBarPanel.SetMaxSize, BinaryRibbonBarPanel.SetMinSize and BinaryRibbonBarPanel.SetResizableSize.

Dialog launcher

With CanShowModalDialog on, a small button beside the title opens the full dialog behind the group – Font, Paragraph, Page Setup: handle ExecuteModalDialogLauncher. ToolTipContent describes it while the pointer is over the button.

Examples

<bm:BinaryRibbonGroup TitleText="Payment" Image="Images/Payment16.png"
                      CanShowModalDialog="True" ExecuteModalDialogLauncher="OnPaymentTerms">
    <bm:BinaryRibbonGroup.ToolTipContent>
        <TextBlock Margin="6" Text="Payment terms: set due dates, discounts and late fees." />
    </bm:BinaryRibbonGroup.ToolTipContent>
    <bm:BinaryRibbonButton Content="Record payment" LargeImage="Images/Payment32.png" Click="OnRecordPayment" />
    <bm:BinaryRibbonButton Content="Refund" SmallImage="Images/Refund16.png" bm:BinaryRibbonBarPanel.MaxSize="Medium" Click="OnRefund" />
    <bm:BinaryRibbonButton Content="Write off" SmallImage="Images/WriteOff16.png" bm:BinaryRibbonBarPanel.MaxSize="Medium" Click="OnWriteOff" />
</bm:BinaryRibbonGroup>
private void OnPaymentTerms(object sender, RoutedEventArgs e)
{
    new PaymentTermsDialog { Owner = this }.ShowDialog();
}

See also

Members at a glance

Constructors
BinaryRibbonGroupCreates an empty group; give it a TitleText and add commands to Controls.
Properties
CanShowModalDialogGets or sets whether the group shows a dialog launcher – the small button beside its title that opens the full dialog behind the group.
ControlsGets the group's commands, in order. This is the group's content in XAML.
ImageGets or sets the picture on the group's button when it has folded away.
IsDropDownActiveGets or sets whether a folded group's drop-down of commands is open.
IsMinimizedGets or sets whether the group is folded into a single button that drops its commands down.
IsSimplifiedGets whether the group is on a ribbon showing the simplified, one-line layout.
IsTitleTextPaneVisibleGets or sets whether the row under the commands – the title and the dialog launcher – is shown.
ItemsPanelGets or sets the panel that lays the group's commands out.
LogicalChildrenGets the group's commands, which are its logical children.
ModalDialogLaunchCommandGets the command the dialog launcher button raises; executed on a group, it raises ExecuteModalDialogLauncher.
ResizingDepthGets or sets how many steps the group has given way to fit the ribbon's width.
TitleTextGets or sets the group's title, shown under its commands, on its folded button and in its drop-down.
ToolTipContentGets or sets what is shown while the pointer is over the dialog launcher button – usually a line on what the dialog offers.
Methods
CollapseResizingLevelTakes the group down one more step, as the ribbon does when it runs out of room.
DeterministicCloseCurrentOpenPopupCloses the drop-down of whichever folded group has one open, on any ribbon.
ExpandResizingLevelBrings the group back up one step, as the ribbon does when it has room again.
OnApplyTemplatePuts the commands into the template's panel, or into its drop-down while the group is folded.
OnControlCollectionChangedCalled when Controls changes; the base implementation works out the commands' sizes again.
OnExecuteModalDialogLauncherCalled when the dialog launcher button is clicked, before handlers further up see the event. The base implementation does nothing; a derived group can open its dialog here.
OnItemsPanelChangedCalled when ItemsPanel changes; the base implementation puts the new panel into the template in place of the old one.
OnLostKeyboardFocusCloses the folded group's drop-down when the keyboard focus leaves the group.
ResetGroupSizeBrings the group back to full size, setting ResizingDepth to 0.
Events
ExecuteModalDialogLauncherOccurs when the user clicks the group's dialog launcher button.
Fields
CanShowModalDialogPropertyIdentifies the CanShowModalDialog dependency property.
ExecuteModalDialogLauncherEventIdentifies the ExecuteModalDialogLauncher routed event.
ImagePropertyIdentifies the Image dependency property.
IsDropDownActivePropertyIdentifies the IsDropDownActive dependency property.
IsMinimizedPropertyIdentifies the IsMinimized dependency property.
IsSimplifiedPropertyIdentifies the IsSimplified dependency property.
IsTitleTextPaneVisiblePropertyIdentifies the IsTitleTextPaneVisible dependency property.
ItemsPanelPropertyIdentifies the ItemsPanel dependency property.
TitleTextPropertyIdentifies the TitleText dependency property.
ToolTipContentPropertyIdentifies the ToolTipContent dependency property.

Constructors

BinaryRibbonGroup

public BinaryRibbonGroup() : base()

Creates an empty group; give it a TitleText and add commands to Controls.

Properties

CanShowModalDialog

public bool CanShowModalDialog

Gets or sets whether the group shows a dialog launcher – the small button beside its title that opens the full dialog behind the group.

Value
The default is false.
Remarks

A click on it raises ExecuteModalDialogLauncher. The button is hidden while IsTitleTextPaneVisible is off.

Controls

public Collection<UIElement> Controls

Gets the group's commands, in order. This is the group's content in XAML.

Image

public ImageSource Image

Gets or sets the picture on the group's button when it has folded away.

Value
The default is null: the folded button shows only the title.

IsDropDownActive

public bool IsDropDownActive

Gets or sets whether a folded group's drop-down of commands is open.

Value
The default is false.
Remarks

Opening one group's drop-down closes any other that is open. A click outside it or on one of its commands closes it.

IsMinimized

public bool IsMinimized

Gets or sets whether the group is folded into a single button that drops its commands down.

Value
The default is false.
Remarks

The group sets it whenever the ribbon resizes it – it is the last of its ResizingDepth steps – so a value set from code lasts only until the next resize.

IsSimplified

public bool IsSimplified

Gets whether the group is on a ribbon showing the simplified, one-line layout.

Value
Set by the ribbon from BinaryRibbonBarPanel.RibbonLayout. The default is false.
Remarks

In the simplified layout the group has no title row, its commands are small pictures with captions on one line, and it folds after two steps. A custom group template can trigger on this property.

IsTitleTextPaneVisible

public bool IsTitleTextPaneVisible

Gets or sets whether the row under the commands – the title and the dialog launcher – is shown.

Value
The default is true.
Remarks

Hiding it hides the dialog launcher with it.

ItemsPanel

public Panel ItemsPanel

Gets or sets the panel that lays the group's commands out.

Value
A panel instance, used by this group alone. The default is null, which lays the commands out in columns: large commands full height, medium and small ones three to a column.
Remarks

The commands in Controls are put into the panel – when the group's template is applied, or at once when the panel is changed later – replacing anything already in it. Add commands to the group, not to the panel.

LogicalChildren

protected override System.Collections.IEnumerator LogicalChildren

Gets the group's commands, which are its logical children.

ModalDialogLaunchCommand static

public static RoutedUICommand ModalDialogLaunchCommand

Gets the command the dialog launcher button raises; executed on a group, it raises ExecuteModalDialogLauncher.

ResizingDepth

public int ResizingDepth

Gets or sets how many steps the group has given way to fit the ribbon's width.

Value
0 (the default) is full size; each step makes commands smaller, and the last folds the group (IsMinimized). A negative value is taken as 0.
Remarks

The ribbon sets it as the window is resized, so a value set from code lasts only until the next resize. Changing it sizes the commands again straight away.

TitleText

public string TitleText

Gets or sets the group's title, shown under its commands, on its folded button and in its drop-down.

Value
A word or two – "Clipboard", "Font". The default is an empty string.

ToolTipContent

public object ToolTipContent

Gets or sets what is shown while the pointer is over the dialog launcher button – usually a line on what the dialog offers.

Value
Any content: text or elements. The default is null.
See also

Methods

CollapseResizingLevel

public bool CollapseResizingLevel()

Takes the group down one more step, as the ribbon does when it runs out of room.

Returns

true if the group went down a step; false if it was already at its last step.

DeterministicCloseCurrentOpenPopup static

public static void DeterministicCloseCurrentOpenPopup()

Closes the drop-down of whichever folded group has one open, on any ribbon.

Remarks

The ribbon calls it when a command is used, so that a drop-down does not stay open over the document. Nothing happens when none is open.

ExpandResizingLevel

public bool ExpandResizingLevel()

Brings the group back up one step, as the ribbon does when it has room again.

Returns

true if the group came up a step; false if it was already at full size.

OnApplyTemplate

public override void OnApplyTemplate()

Puts the commands into the template's panel, or into its drop-down while the group is folded.

OnControlCollectionChanged

protected virtual void OnControlCollectionChanged(object sender, System.Collections.Specialized.NotifyCollectionChangedEventArgs e)

Called when Controls changes; the base implementation works out the commands' sizes again.

Parameters
sender
The collection.
e
The commands added or removed.

OnExecuteModalDialogLauncher

protected virtual void OnExecuteModalDialogLauncher(object sender, RoutedEventArgs e)

Called when the dialog launcher button is clicked, before handlers further up see the event. The base implementation does nothing; a derived group can open its dialog here.

Parameters
sender
The group.
e
The event data.

OnItemsPanelChanged

protected virtual void OnItemsPanelChanged(DependencyPropertyChangedEventArgs e)

Called when ItemsPanel changes; the base implementation puts the new panel into the template in place of the old one.

Parameters
e
The old and new panels.

OnLostKeyboardFocus

protected override void OnLostKeyboardFocus(KeyboardFocusChangedEventArgs e)

Closes the folded group's drop-down when the keyboard focus leaves the group.

Parameters
e
The data for the event.

ResetGroupSize

public void ResetGroupSize()

Brings the group back to full size, setting ResizingDepth to 0.

Events

ExecuteModalDialogLauncher

public event RoutedEventHandler ExecuteModalDialogLauncher

Occurs when the user clicks the group's dialog launcher button.

Remarks

A bubbling routed event, so one handler higher up can serve several groups and tell them apart by RoutedEventArgs.Source. Open the dialog the group stands for. The button is on show only while CanShowModalDialog and IsTitleTextPaneVisible are on.

Fields

CanShowModalDialogProperty static

public static readonly DependencyProperty CanShowModalDialogProperty

Identifies the CanShowModalDialog dependency property.

ExecuteModalDialogLauncherEvent static

public static readonly RoutedEvent ExecuteModalDialogLauncherEvent

Identifies the ExecuteModalDialogLauncher routed event.

ImageProperty static

public static readonly DependencyProperty ImageProperty

Identifies the Image dependency property.

IsDropDownActiveProperty static

public static readonly DependencyProperty IsDropDownActiveProperty

Identifies the IsDropDownActive dependency property.

IsMinimizedProperty static

public static readonly DependencyProperty IsMinimizedProperty

Identifies the IsMinimized dependency property.

IsSimplifiedProperty static

public static readonly DependencyProperty IsSimplifiedProperty

Identifies the IsSimplified dependency property.

IsTitleTextPaneVisibleProperty static

public static readonly DependencyProperty IsTitleTextPaneVisibleProperty

Identifies the IsTitleTextPaneVisible dependency property.

ItemsPanelProperty static

public static readonly DependencyProperty ItemsPanelProperty

Identifies the ItemsPanel dependency property.

TitleTextProperty static

public static readonly DependencyProperty TitleTextProperty

Identifies the TitleText dependency property.

ToolTipContentProperty static

public static readonly DependencyProperty ToolTipContentProperty

Identifies the ToolTipContent dependency property.