RibbonClipping

The DotNetBar for Silverlight Ribbon control is an implementation of the Microsoft Ribbon for your Silverlight applications. It is designed to match the Ribbon found in Microsoft Office 2010 programs very closely. DevComponents Ribbon is a full featured ribbon control – you can now design your Silverlight applications around a Ribbon based user interface without compromise in either form or function.

A list of important features implemented in the current release includes:

  • 3 color themes included by default: Office2010Blue, Office2010Silver and Office2010Black
  • A full set of controls designed for the Ribbon, including:
    • Button, ToggleButton, RadioButton
    • DropDownButton
    • SplitButton
    • ComboBox
    • MenuItem
    • Gallery
    • InRibbonGallery
    • LayoutControl
  • Normal, Minimized, Collapsed and open in Popup views.
  • Toggle IsMinimized state with double click on Ribbon Tab Item.
  • Fully automated resizing. Ability to define exact order in which groups of controls are resized.
  • Ribbon tool tips – placement and look just like in Office 2010.
  • Command previewing (Gallery only)
  • File button opens any content you define
  • Ability to place your own controls at right side of tab items.
  • Full featured Quick Access Toolbar
  • Customizable Context Menu
  • 2010 style Backstage

Content Model

Here is a minimal Ribbon defined in Xaml showing the hierarchy of elements which make up a Ribbon UI (for a more complete example, check out the sample RibbonControlSample that is included in the DotNetBar for Silverlight installation):

<r:Ribbon>
    <r:Ribbon.QuickAccessToolbar>
        <r:QuickAccessToolbar ActiveItems="New" ApplicationImageSource="/RibbonControlSample;component/Images/Component.png">
            <r:Button r:QuickAccessToolbar.DisplayName="New" SmallImageSource="/RibbonControlSample;component/Images/Application/New16.png" />
            <r:Button r:QuickAccessToolbar.DisplayName="Open" SmallImageSource="/RibbonControlSample;component/Images/Application/Open16.png" />        
        </r:QuickAccessToolbar>
    </r:Ribbon.QuickAccessToolbar>
    <r:Ribbon.SystemToolbarItems>
        <ToggleButton Style="{StaticResource ExpandCollapseToggleButtonStyle}"
                        IsChecked="{Binding ElementName=ribbon, Path=IsMinimized, Mode=TwoWay}" />
    </r:Ribbon.SystemToolbarItems>
    <r:Ribbon.BackstageContent>
        <Border />
    </r:Ribbon.BackstageContent>
    <r:RibbonTabItem Label="Home">
        <r:RibbonBar Label="Clipboard" ImageSource="Images/Paste16.png" IsLauncherVisible="True">
            <r:SplitButton Label="Paste" LargeImageSource="Images/Paste32.png" SmallImageSource="Images/Paste16.png">
                <r:Gallery CanResizeHorizontally="True" CanResizeVertically="True">
                    <r:GalleryCategory Header="Paste Options">
                        <r:GalleryItem>
                            <Image Source="Images/KeepFormatting" />
                        </r:GalleryItem>
                    </r:GalleryCategory>
                </r:Gallery>
            </r:SplitButton>
            <r:Button Label="Copy" LargeImageSource="Images/Copy32.png" SmallImageSource="Images/Copy16.png" />
        </r:RibbonBar>
        <r:RibbonBar Label="Font">
            <r:LayoutControl>
                <r:ComboBox>
                    <r:Gallery />
                </r:ComboBox>
                <r:Button SmallImageSource="Images/Bold16.png" />
                <r:Button SmallImageSource="Images/Italic16.png" />
            </r:LayoutControl>
        </r:RibbonBar>
    </r:RibbonTabItem>
</r:Ribbon>

 

Ribbon

DevComponents.Silverlight.Ribbon.Ribbon is the top level container for all that makes up a Ribbon UI. Ribbon inherits from ItemsHostControl and is meant to contain a collection of RibbonTabItem. Inserting any other type of UI Element into a Ribbon’s Items collection will not raise an exception but neither will the element be rendered. Objects in the Items collection can be instances of RibbonTabItem or they can be any regular CLR object. If the latter, it is necessary to provide a value for ItemTemplate – a DataTemplate which shows how to render the objects. Alternatively, you can define typed data template(s) for the items. Important: the data template, however it is supplied, must have a RibbonTabItem as its top level element if it is to be rendered.

Ribbon’s SystemToolbarItems is a read-only property that returns a reference to an ObservableCollection<UIElement>. All items in the collection are rendered on the far right of the Ribbon, at the same vertical level as the ribbon tab items. By default, this collection is empty.

The QuickAccessToolbarItems read-only property is likewise an ObservableCollection collection of UIElements. All items placed in this collection are rendered on the top left corner of the Ribbon control’s boundaries. Note: this property is subject to change. It serves mainly as a place holder for the real QuickAccessToolbar when implemented in the final release. The quick access toobar (QAT) can be shown or hidden via the QuickAccessToolbarVisibility property.

Ribbon.BackstageContent is used to set the object which is displayed in the Popup when the Backstage (or File) toggle button is checked. By default this property is null. Note that if the value for BackstageContent is not a UIElement, then a data template is needed which shows how to render the object. Set this data template via the BackstageContentTemplate property. To get or set whether the backstage is  open, use the IsBackStageOpen property.

By default the Backstage button displays the text "File". This can be changed via the BackstageButtonContent property. To hide the backstage button altogether, set BackstageButtonVisibility = false.

The Ribbon always displays the content provided by the currently selected item. Get or set the currently selected item via the SelectedItem dependency property. If items in the Items collection are not themselves RibbonTabItems, you can access the RibbonTabItem serving as container for any given item via the method GetContainerFromItem (inherited from ItemsHostControl)

The ribbon can be minimized by setting the IsMinimized property to true. When minimized, the tab items are visible but the content is hidden. When minimized, the content can be shown in a popup by setting IsPopupOpen to true. If a user clicks on a tab when the Ribbon is minimized, the tab item will be selected and the popup will open to show the content. By default, the user can toggle between minimized and not minimized state by double clicking on a tab item. This can be overridden by setting DoubleClickTabToggleEnabled = false.

The ribbon can be collapsed by setting IsCollapsed = true. When collapsed, no portion of the Ribbon is visible. By default, the ribbon collapses automatically when either its width or the height of the hosting Silverlight application reach certain minimum values. These values are defined in RibbonResources as RibbonCollapseWidth and RibbonCollapseApplicationHeight, respectively.

RibbonTabItem

DevComponents.Silverlight.Ribbon.RibbonTabItem is the second level container for all that makes up a Ribbon UI. RibbonTabItem is not an ItemsHostControl, but it does contain a collection of Items, which can be populated via binding to an ItemsHost and rendered according to an ItemTemplate. (The reason that RibbonTabItem does not inherit from ItemsHostControl is because it does not actually display the items in its collection. The Ribbon control is responsible for displaying the selected tab item’s content.) Objects in a tab item’s Items collection can be instances of any UIElement, however, RibbonBar is the intended container and using it will enable advanced functionality such as automatic resizing. Regular CLR objects can also be content items, but, as with the Ribbon control, using regular CLR objects requires a DataTemplate to show how to render the objects (supplied either via the ItemTemplate property or typed data template(s), also like the Ribbon control.)

The Label property sets the string value which is displayed by the tab item.

Use IsSelected to get or set whether the tab item is selected. Setting this property to true will change the value of Ribbon.SelectedItem.

To specify the order in which the contained ribbon bars are automatically ,resized, use RibbonBarResizeOrder. This is a string of comma separated values, either names of the ribbon bar elements to be resized or their index number in the Items collection. Note that only ribbon bars can participate in automatic resizing of the ribbon tab content.

RibbonBarResizeOrder is used to create a stack of references to RibbonBars, defining the order in which they are shrunk as the Ribbon is made smaller, beginning with a fully expanded Ribbon. So, assume that the Ribbon is fully expanded, such that every RibbonBar is at its maximum width. Now, user begins a resize operation, making the Ribbon smaller. When the Ribbon size reaches a point where something needs to be made smaller, the RibbonBar that referenced by the Top item of the stack created from RibbonBarResizeOrder will be shrunk. After one is shrunk, it is removed from that stack and placed into another stack containing references to the RibbonBars that have been shrunk already, creating a reverse path for expanding the ribbon.

RibbonBar

DevComponents.Silverlight.Ribbon.RibbonBar is the third level container for all that makes up a Ribbon UI. RibbonBar inherits from ItemsHostControl. RibbonBar can contain any UIElement, however, only certain Types are able to participate in auto sizing. The Types that can participate in RibbonBar auto sizing are:

  • All buttons which inherit from DevComponents.Silverlight.Ribbon.ButtonBase. Includes Button, ToggleButton, RadioButton, DropDownButton, SplitButton.
  • LayoutControl

The Label property sets the string value which is displayed by the ribbon bar along its bottom edge.

A button can be displayed on the bottom right corner of the bar by setting IsLauncherVisible to true. Clicking this button raises the LauncherClicked routed event. Properties LauncherCommand and LauncherCommandParameter are also available. If set, the launcher command is executed immediately after the clicked event is raised. (You can prevent the command from executing by setting the event argument’s Handled property to true.)

When a ribbon bar has exhausted the ability of its contents to shrink, the final step is for the bar to collapse. When in the collapsed state, the ribbon bar displays an icon meant to represent all the items in the bar. This image is set via the ImageSource property (for best results, the image should be 16×16 pixels in size.) Also, the bar is transformed in to a toggle button which when checked opens a popup displaying all the normal contents of the bar in their full size. You can get or set whether this popup is open via the IsPopupOpen property. To prevent a ribbon bar from collapsing, set IsCollapsable to false. To get or set whether a ribbon bar is in the collapsed state, use the IsCollapsed property.

As an example, consider the RibbonControlSample which is included in the DotNetBarSilverlight installation. With the Sample, the InRibbonGallery containing the quick styles is set to display a maximum number of items per row of 7. So when the Ribbon is fully expanded there are 7 items in the InRibbonGallery. Now when ribbon is resized, made smaller, we want the first 4 items in the InRibbonGallery to be removed before anything else. Each time one is removed, the corresponding entry in the RibbonBarResizeOrder stack is Popped off. That is why there are Styles 4 times. In the Sample there is another group of 3 Styles which are telling the system when the remaining items in the InRibbonGallery can be shrunk. In all, there are a total of 7 steps required to shrink the InRibbonGallery from fully expanded to collapsed.

LayoutControl

DevComponents.Silverlight.Ribbon.LayoutControl is used to perform custom layout of the controls which are placed inside it.  Use LayoutControl as a direct child of RibbonBar. LayoutControl inherits from ItemsHostControl and can display any type of UIElement. It is most common, however, to use controls that are defined in the DevComponents.Silverlight.Ribbon namespace for the enhanced support they provide for advanced Ribbon features, as well as styling considerations.

Layout control arranges the items (or their containers) in its Items collection according to a LayoutDefinition. A layout definition defines the positioning of the elements, by row and by index. LayoutDefinition contains a collection of one or more LayoutRow. Each layout row has one or more LayoutGroup and each layout group is a collection of LayoutRef. Note that layout groups defined on the same row will be separated by a Separator. LayoutRef is a place holder for a specific UI element that has been placed into the LayoutControl. Elements can be referenced either by Name or by their (zero based) index position within the Layout control’s Items collection. The optional ElementRef.ElementWidth allows a specific width be set on the element. Here is an example of a complete LayoutDefinition that has three rows defined:

<r:LayoutDefinition>
    <r:LayoutRow>
        <r:LayoutGroup>
            <r:ElementRef ElementName="FontFamilyComboBox" ElementWidth="125" />
            <r:ElementRef ElementName="FontSizeComboBox" ElementWidth="45"/>
        </r:LayoutGroup>
    </r:LayoutRow>
    <r:LayoutRow>
        <r:LayoutGroup>
            <r:ElementRef ElementName="BoldButton" />
            <r:ElementRef ElementName="ItalicButton" />
            <r:ElementRef ElementName="UnderlineButton" />
            <r:ElementRef ElementName="StrikethroughButton" />
            <r:ElementRef ElementName="SuperscriptButton" />
            <r:ElementRef ElementName="SubscriptButton" />
        </r:LayoutGroup>
        <r:LayoutGroup>
            <r:ElementRef ElementName="ClearFormattingButton" />
        </r:LayoutGroup>
    </r:LayoutRow>
    <r:LayoutRow>
        <r:LayoutGroup>
            <r:ElementRef ElementName="TextEffectsButton" />
            <r:ElementRef ElementName="HighlightButton" />
            <r:ElementRef ElementName="FontColorButton" />
            <r:ElementRef ElementName="ChangeCaseButton" />
        </r:LayoutGroup>
        <r:LayoutGroup>
            <r:ElementRef ElementName="GrowFontButton" />
            <r:ElementRef ElementName="ShrinkFontButton" />
        </r:LayoutGroup>
    </r:LayoutRow>
</r:LayoutDefinition>

A layout control can have one or more layout definitions in its LayoutDefinitions collection. The purpose of this is to allow different sized layouts to be defined. When the Ribbon is being resized, the layout control shrinks or expands itself by rendering its content based on the most appropriate sized layout definition.

Buttons

All buttons defined in the DevComponents.Silverlight.Ribbon namespace inherit from ButtonBase. Available buttons are Button, ToggleButton, RadioButton, DropDownButton and SplitButton. Buttons are designed to be children of both the ribbon bar and the layout control. They can also be placed inside a Gallery.

One important function of ButtonBase is to provide support for button auto sizing. All buttons can be displayed in three sizes: Large, Medium and Small. At what size a button is rendered at any given layout pass is determined by the auto size algorithm, which is described below. To set a minimum size for a button, use the property MinimumSizeState. For example, to ensure that a button remains in the large state during auto sizing, set MinimumSizeState = ButtonSizeState.Large.

To set the text displayed by the button, use the property Label. The image displayed by the button when in its large state is set via the LargeImageSource property. This is a Uri which should refer to an image that is 32×32 pixels in size. The image displayed when the button is in the medium and small states is set via SmallImageSource. This Uri should refer to an image that is 16×16 pixels in size. Note: If a large image is not specified, then the button will never be rendered in the large size. Likewise with the small image. Not setting it will effectively prevent the button from taking on the medium or small sizes.

Note that ButtonBase inherits from ContentControl, so it has a Content property. If Content is set, then Label, LargeImageSource and SmallImageSource are ignored. Note as well that setting a value for Content will make the button unable to participate in auto sizing.

ButtonBase exposes a Click event as well as properties Command and CommandParameter.

A DropDownButton is essentially a toggle button which, when checked, opens a popup up. There are no limitations on what can be shown in the drop down button’s popup. Note that DropDownButton overrides the base class behavior by disabling the Click event and command execution.

A SplitButton is a combination of a Button and a DropDownButton. The top portion of the split button is the button part; it will fire the Click event and execute the button’s Command when clicked. The bottom portion is the drop down button. It will open the popup which displays the button’s content.

Gallery

DevComponents.Silverlight.Ribbon.Gallery is a specialized control for displaying a collection of items which are optionally organized into categories. There is the option of including a Menu which is positioned at the bottom of the gallery. A Gallery is a collection of GalleryCategory objects while GalleryCategory is a collection of GalleryItem objects. The following Xaml shows the hierarchy:

<r:Gallery AreGalleryItemsSelectable="False">                                                        
    <r:GalleryCategory Header="Paste Options:">
        <r:GalleryItem r:Ribbon.ToolTip="Keep Source Formatting">
            <Image Source="/RibbonControlSample;component/Images/Paste_KeepSourceFormatting.png" />
        </r:GalleryItem>
        <r:GalleryItem r:Ribbon.ToolTip="Merge Formatting">
            <Image Source="/RibbonControlSample;component/Images/Paste_MergeFormatting.png" />
        </r:GalleryItem>
        <r:GalleryItem r:Ribbon.ToolTip="Keep Text Only">
            <Image Source="/RibbonControlSample;component/Images/Paste_KeepTextOnly.png" />
        </r:GalleryItem>
    </r:GalleryCategory>
    <r:Gallery.MenuItems>
        <r:MenuItem Header="Paste Special..." r:Ribbon.ToolTipHeader="Paste Special (Alt+Ctrl+V)" r:Ribbon.ToolTipContent="Select from available formats currently in the clipboard."/>
        <r:MenuItem Header="Set Default Paste..." />
    </r:Gallery.MenuItems>
</r:Gallery>

A Gallery is generally used as the content of the popup of a drop down button or combo box.

Use GalleryCategory.Header to set the category header. Note in the example above the use of Gallery.MenuItems for creating a menu.

Both Gallery and GalleryCategory are ItemsHostControls, so their content can be defined as a collection of regular CLR objects bound via the ItemsSource property, using a DataTemplate which provides the visual element for their display. Data template can be set on individual gallery categories, or it can be set once for all categories via the Gallery.GalleryItemTemplate property. Here is an example:

<r:Gallery CanResizeVertically="True" MaxColumnCount="1"                                        
            Command="{Binding Source={StaticResource Model},Path=FontFamilyCommand}">
    <r:Gallery.GalleryItemTemplate>
        <DataTemplate>
            <TextBlock Text="{Binding Source}" FontFamily="{Binding}" FontSize="14"/>
        </DataTemplate>
    </r:Gallery.GalleryItemTemplate>
    <r:GalleryCategory Header="Recent Fonts" ItemsSource="{Binding RecentFontFamilies}" />
    <r:GalleryCategory Header="All Fonts" ItemsSource="{Binding FontFamilies}" />
</r:Gallery>

To set the maximum number of columns that the gallery will display, use property Gallery.MaxColumnCount and use Gallery.MinColumnCount to specify a minimum. Note that the example above is defining a one column display by setting MaxColumnCount = 1. To define the initial column count when the gallery is first opened, use property Gallery.InitialColumnCount.

By default, all columns share the same width and height across the whole Gallery. To make is so the items in one category can be sized differently than the items in the other categories, set its IsSharedSizeColumnSizeScope property to true. To make it so all gallery items are individually sized, set IsSharedColumnSizeScope = false on the gallery as well as the categories.

To enable resizing in the vertical direction, use Gallery.CanResizeVertically and in the horizontal direction, Gallery.CanResizeHorizontally.

To get or set the currently selected gallery item, use Gallery.SelectedItem. It is possible to make it so gallery items are not selectable, but still raise their Click and other events. To make is so gallery items are not selectable, set AreGalleryItemsSelectable = false. (This property is available on both Gallery and GalleryCategory.)

Both Gallery and GalleryCategory have a Command and associated CommandParameter property. For each, the command is executed when a gallery item contained within is clicked. A command specified at the gallery level is only executed if the category which contains the triggering gallery item does not have a command. CommandParameterValuePath is an additional property shared by both that can be used to specify a command parameter. It is a string value specifying a property path from which to obtain the parameter value. The property path is relative to the item for which the gallery item that triggered the command execution is a container.

Command Previewing – the ability to preview the effects of a command without permanently applying it – is supported by Gallery. To enable command previewing, set either Gallery.Command or GalleryCategory.Command to an object which implements interface DevComponents.Silverlight.Controls.IPreviewCommand. DevComponents.Silverlight.Controls.RelayPreviewCommand, which is based on RelayCommand is such a command. The Preview method will be executed when a gallery item is highlighted, and the CancelPreview method is executed when the gallery item exits the highlighted state.

InRibbonGallery

DevComponents.Silverlight.Ribbon.InRibbonGallery is a specialized Gallery and in fact inherits from Gallery. InRibbonGallery is a dual state control. In its "In Ribbon" state it displays a collection of un categorized items. This view includes a toggle button for opening the Gallery – which opens a popup containing the standard Gallery as discussed above. Since InRibbonGallery inherits from Gallery all inherited properties are available for controlling the display of the popup gallery.

Use InRibbonMaxColumnCount and InRibbonMinColumnCount for setting the minimum and maximum number of items per row for the "In Ribbon" view.

Property IsGalleryOpen is used to determine whether the Gallery popup is open.

The control has a collapsed state, when it is resized to the point where it can be sized no smaller. Use property IsCollapsed to get or set whether the control is collapsed. When collapsed, InRibbonGallery is effectively the same as a DropDownButton. Use CollapsedLabel to set the its label when collapsed and CollapsedImageSource for the image. To make is so the InRibbonGallery does not enter the collapsed state, set CanCollapse false.

ComboBox

DevComponents.Silverlight.Ribbon.ComboBox is an editable combo box with integrated support for hosting a Gallery. ComboBox inherits from ItemsHostControl. The native container for combo box is the ComboBoxItem. However, a single instance of Gallery can be set as the single item in the combo box’s Items collection. Here is an example of a gallery hosted by a combo box:

<r:ComboBox Name="FontSizeComboBox" DisplayMemberPath="Content" IsEditable="True" Text="{Binding FontSizeText, Mode=TwoWay}"      
            r:Ribbon.ToolTipHeader="Font Size" r:Ribbon.ToolTipContent="Change the font size." SelectedIndex="5">
    <r:Gallery CanResizeVertically="True" MaxColumnCount="1" Command="{Binding FontSizeCommand}" CommandParameterValuePath="Content">
        <r:GalleryCategory>
            <r:GalleryItem Content="8" />
            <r:GalleryItem Content="9" />
            <r:GalleryItem Content="10" />
            <r:GalleryItem Content="11" />
            <r:GalleryItem Content="12" />
            <r:GalleryItem Content="14" />
            <r:GalleryItem Content="16" />
            <r:GalleryItem Content="18" />
            <r:GalleryItem Content="20" />            
        </r:GalleryCategory>
    </r:Gallery>
</r:ComboBox>

In this case, ComboBox.SelectedItem and Gallery.SelectedItem will always point to the same object.

To make a combo box editable, set IsEditable = true. This will make it so the end user can type into the combo box’s selection box. When typing, the display value of matching items are automatically filled in to complete the text. What happens if the user enters a text value for which there is no matching item in the collection is determined by the IsReadonly property. When IsReadonly is false, then it is actually not possible for the end user to enter a value which does not already exist in the collection. When IsReadonly is true, the end user is free to enter any value. You can listen for a TextChanged event to know when the user typed in a new value. TextChanged is raised when the new text is committed either by the combo box losing focus or the enter key being pressed. The value entered by the user is stored in property ComboBox.Text. (Note: Text is a read/write property, you can use it to set the displayed text as well.)

Quick Access Toolbar

To enable the Quick Access Toolbar, it is necessary to set a value for property Ribbon.QuickAccessToolbar. This is a dependency property of type DevComponents.Silverlight.Ribbon.QuickAccessToolbar and it’s default value is null. Here is an example of how to set up the QAT for a Ribbon:

<r:Ribbon>
    <r:Ribbon.QuickAccessToolbar>
        <r:QuickAccessToolbar ActiveItems="New, Open, Save" ApplicationImageSource="/RibbonControlSample;component/Images/Component.png">
            <r:Button r:QuickAccessToolbar.DisplayName="New" SmallImageSource="/RibbonControlSample;component/Images/Application/New16.png" />
            <r:Button r:QuickAccessToolbar.DisplayName="Open" SmallImageSource="/RibbonControlSample;component/Images/Application/Open16.png" />
            <r:Button r:QuickAccessToolbar.DisplayName="Save" SmallImageSource="/RibbonControlSample;component/Images/Application/Save16.png" />
            <r:Button r:QuickAccessToolbar.DisplayName="Print" SmallImageSource="/RibbonControlSample;component/Images/Application/Print16.png" />
            <r:Button r:QuickAccessToolbar.DisplayName="Print Preview" SmallImageSource="/RibbonControlSample;component/Images/Application/PrintPreview16.png" />
            <r:Button r:QuickAccessToolbar.DisplayName="Undo" SmallImageSource="/RibbonControlSample;component/Images/Application/Undo16.png" />
            <r:Button r:QuickAccessToolbar.DisplayName="Redo" SmallImageSource="/RibbonControlSample;component/Images/Application/Redo16.png" />
        </r:QuickAccessToolbar>
    </r:Ribbon.QuickAccessToolbar>
</r:Ribbon>

QuickAccessToolbar is an ItemsControl. Add controls to its Items collection which are not contained in the Ribbon but which you want to be available in the QAT. The attached property QuickAccessToolbar.DisplayName is used for listing the item in the customize menu, which is accessed by clicking on the customize button.

Any control contained with-in the Ribbon can be added to the QAT if it implements interface ISupportQuickAccessToolbar. ISupportQuickAccessToolbar defines method CloneForQuickAccessToolbar and method GetCloneIdModifier. The clone method should do just what it says, create a "clone" of the control which can be added to the QAT without violating the Silverlight rule that a UIElement can have only one visual parent. The id modifier is there to support controls which may have more than one clone implementation depending on where the mouse is located when the context menu containing the menu item for adding the item to the QAT is opened.

To prevent a control from being addable to the QAT, use the attached property QuickAccessToolbar.CanAddToQuickAccessToolbar.

Any controls which is added to the Quick Access Toolbar are given an Id. You can set this Id explicitly using the attached property QuickAccessToolbar.Id. If this property is not set, then the control’s Name property is used, and if it is not set, the value for QuickAccessToolbar.DisplayName. Finally, the control’s runtime value returned by GetHashCode() is used as the quick access toolbar id. As a general rule, if you use the quick access toolbar, then all controls in the Ribbon that can be added to it should be given either a Name or a QuickAcessToolbar.Id.

All available properties which affect the quick access toolbar are defined as members of QuickAcessToolbar (not Ribbon). These include:

  • AboveRibbonMargin – specifies a margin for the toolbar content when it is positioned above the ribbon.
  • ActiveItems – get or set a comma separated list of QAT Ids of the items currently active in the QAT.
  • ApplicationImageSource – source for the image that is displayed at the front of the Quick Access Toolbar.
  • CustomizeButtonVisibiliby – determines whether the Customize button is visible. Default value is true.
  • IsToolbarLocked – when true, items cannot be either added or removed from the QAT. Default value is false.
  • IsPositionLocked – when true, the QAT cannot be moved from its current position, whether above or below the Ribbon. Default value is false.
  • Position – determines the position of the QAT relative to the Ribbon. Possible values are AboveRibbon and BelowRibbon. Default value is AboveRibbon.

A note on Icons for Ribbon controls when added to the QAT. Attached property QuickAccessToolbar.QATImageSource can be set on any control to explicitly set the image source for the QAT. This should reference an image that is 16×16 pixels. If QATImageSource is not set, then an image already owned by the control is used. The buttons defined in the DevComponents.Silverlight.Ribbon namespace, namely Button, ToggleButton, RadioButton, DropDownButton and SplitButton, use the original control’s SmallImageSource as source for the icon.  ComboBox doesn’t require an icon. InRibbonGallery uses its CollapsedImageSource (which is meant to be an image 32×32 pixels, so it is best to set QuickAccessToolbar.QATImageSource for InRibbonGallery.) MenuItem uses its IconSource property. If an image is otherwise unavailable for the QAT, then a default image is used.

Ribbon Context Menu

DevComponents.Silverlight.Ribbon.RibbonContextMenu is a specialized Context Menu that contains the logic for updating its menu items to add or remove a specific control from the QAT. It also includes, when property values allow, menu items for minimizing the Ribbon and moving the Quick Access Toolbar above or below the Ribbon. Property Ribbon.ContextMenu is a dependency property of type RibbonContextMenu. By default, the Ribbon’s context menu is set to a new instance of RibbonContextMenu. To disable the context menu altogether, set this value to null (either in code or in Xaml using {x:Null}).

There are several way to customize the ribbon context menu. One way is to declare your own instance of RibbonContextMenu and add your custom menu items to it, which will remain in the context menu when ever it opens. Another way to customize the context menu would be to handle either ContextMenu.Opening routed event or the ContextMenu.Opened Clr event. In either case, the sender of the event will be the Context Menu itself, which you can modify at runtime depending on the location of the mouse when the menu receives notice to open. This position is stored in the PlecementPosition property of the context menu.

Alternatively, the original source element of the mouse event is stored in property OriginalOpeningSource of the RibbonContextMenu object.

Another way to customize the context menu via the attached property RibbonContextMenu.CustomMenuItems, which is a collection of type DevComponents.Silverlight.Ribbon.CustomMenuItemCollection. When the ribbon context menu is opening and it encounters an element having a value for this property in the visual tree path from where the original mouse event originated to the Ribbon itself, then the items in the collection are added to the items in the context menu when it opens. Note that these custom menu items are cumulative, that is, custom menu items can be defined at any level and all will be included.

A common scenario is to have custom menu items for the gallery items within a Gallery. The most efficient way to achieve this is to define a Style for the GalleryItem at the level of the Gallery which has a property setter for the attached property RibbonContextMenu.CustomMenuItems. Here is an example:

<r:InRibbonGallery.Resources>
    <Style TargetType="r:GalleryItem">
        <Setter Property="r:RibbonContextMenu.CustomMenuItems">
            <Setter.Value>
                <r:CustomMenuItemCollection>
                    <r:MenuItem Header="Edit Properties" />
                    <r:MenuItem Header="Remove from Gallery" Click="RemoveStyleFromGalleryCustomMenuItem_Click"/>
                </r:CustomMenuItemCollection>
            </Setter.Value>
        </Setter>
    </Style>
</r:InRibbonGallery.Resources>

The strings used for menu items created by RibbonContextMenu can be modified via the property RibbonContextMenu.TextProvider. This property is of type IRibbonContextMenuTextProvider and the default property value is an instance of class RibbonContextMenuTextProvider.

A note about the default behavior of RibbonContextMenu when opening from within a Gallery. The default behavior in this case is to remove all menu items except for the one that allows the gallery to be added to the quick access toolbar and any custom menu items that might be defined. This behavior mimics Microsoft Office 2010. To disable this behavior, set property RibbonContextMenu.HideItemsWhenOpenInGellery to false (its default value is true.)

Ribbon Tool Tips

Tool tips for Ribbon elements are instances of SuperToolTip.

You can define a ribbon tool tip for any element that you place in the Ribbon, whether or not it is part of the DevComponents.Silverlight.Ribbon namespace. A set of attached properties are used to define tool tips, associate them with specific elements and position them correctly. The attached properties are defined on class Ribbon:

  • Ribbon.ToolTipHeader – Creates the tool tip if it doesn’t exist and sets its Header property.
  • Ribbon.ToolTipContent – Creates the tool tip if it doesn’t exist and sets the Content property.
  • Ribbon.ToolTipFooter – Creates the tool tip if it doesn’t exist and sets its Footer property.
  • Ribbon.ToolTipFooterImageSource – Creates the tool tip if it doesn’t exist and sets its FooterImageSource property.

And one to rule them all:

  • Ribbon.ToolTip – Use to get or set the SuperToolTip directly. Necessary if you need more control over the tool tip than afforded by the 4 properties above.

Here is Xaml for a ribbon Button that has had all 4 of the above properties set:

<r:Button Label="Format Painter" SmallImageSource="/RibbonControlSample;component/Images/FormatPainter16.png" 
          r:Ribbon.ToolTipHeader="Apply Formatting" 
          r:Ribbon.ToolTipContent="Copy formatting from one place and apply it to another."
          r:Ribbon.ToolTipFooter="Hit F1 for more information"
          r:Ribbon.ToolTipFooterImageSource="/RibbonControlSample;component/Images/Help16.png" />

Similarly in c#:

var button = new R.Button
    {
        Label = "Format Painter",
        SmallImageSource = new Uri("Images/FormatPainter16.png", UriKind.Relative)
    };
Ribbon.SetToolTipHeader(button, "Apply Formatting");
Ribbon.SetToolTipContent(button, "Copy formatting from one place and apply it to another");
Ribbon.SetToolTipFooter(button, "Hit F1 for more information");
Ribbon.SetToolTipFooterImageSource(button, new Uri("Images/Help16.png", UriKind.Relative));

Backstage

Support for Office 2010 style Backstage is provided by the control DevComponents.Silverlight.Ribbon.Backstage. To use Backstage simply create an instance and set is as value of property Ribbon.BackstageContent. Here is an example:

<r:Ribbon BackstageButtonVisibility="Visible" BackstageColor="Orange"
     RibbonApplicationBoundingElement="{Binding ElementName=ApplicationBorder}">
    <r:Ribbon.BackstageContent>
        <r:Backstage>
            <r:BackstageButton Content="Open" IconSource="Images/Open.png" />
            <r:BackstageTab Header="Recent">
 
            </r:BackstageTab>
        </r:Backstage>
    </r:Ribbon.BackstageContent>
</r:Ribbon>

Notice that BackstageContent is type object so that, along with property BackstageContentTemplate, any object can serve as the backstage. The backstage, whatever the actual content, can be opened or closed programmatically via property Ribbon.IsBackstageOpen. The event IsBackstageOpenChanged fires whenever the value changes. The built-in backstage button (or file button) can be hidden by setting Ribbon.BackstageButtonVisibility = false.

There are four built-in color themes for the Backstage: blue, green, orange and magenta. The active color theme is set via property Ribbon.BackstageColor. (This is a property of the Ribbon control because it is used for the backstage button, which is separate from the Backstage.) It is possible to customize any part of all of the backstage color theme. The DynamicResourceDictionary used to provide resources for backstage control rendering is accessible via property Ribbon.BackstageResources.

Backstage will automatically size itself to match the bounds of the FrameworkElement Ribbon.RibbonApplicationBoundingElement, if this property is set. RibbonApplicationBoundingElement should be bound to a FrameworkElement in your Silverlight application whose boundaries represent the bounds of the application of which the Ribbon is a part.  If not set, the client is responsible for managing Backstage size.

The Backstage control is a ItemsHostControl so any object can be added to it. Two controls designed and styled specifically for Backstage are provided: BackstageTab and BackstageButton. BackstageButton is simply a Silverlight Button control with an additional property IconSource and a default Style to match the Backstage theme.

BackstageTab.Header sets the value displayed by the Tab and BackstageTab.Content determines the content displayed by the Backstage when the Tab is selected. A BackstageTab can be selected or unselected via property IsSelected.

Auto Sizing

Ribbon is fully resizable. Its content will automatically re-arrange itself to grow or shrink as necessary to fit into the available width. (Note: the ribbon’s height is a fixed value and does not change during resizing. However, it can be changed from the default by setting the static property RibbonResources.RibbonContentHeight before the Ribbon loads.)

When the ribbon is being resized to a smaller width and the width of the current content is greater than the available width, something needs to shrink. The current content is provided by the currently selected RibbonTabItem, and generally is a collection of RibbonBar items. (Content placed in a tab item outside of a ribbon bar is not resizable.) By default, each ribbon bar is queried for the number of pixels it would shrink by if it were to actually shrink one step less wide than its current state. The bar which return the smallest non-zero value is then asked to actually shrink itself. As the ribbon is resizing this process is repeated until all bars have shrunk to their smallest size possible. When resizing in the other direction, that is when the ribbon is being made wider, the bars are expanded in the reverse order in which they were shrunk.

A RibbonBar resizes itself by resizing and/or repositioning its contents. However, not every UIElement supports being resized by the ribbon bar. Only buttons which inherit from DevComponents.Silverlight.Ribbon.ButtonBase and the LayoutControl (and InRibbonGallery when ready) can be intelligently resized.

Tip: Buttons are resized in groups of three or less. To form a group, buttons must be adjacent to each other, be the same size (i.e. small, medium or large) and all support the same sizes. Groups are formed from right to left. Groups of two are formed if group of three is not available.

Related posts:

  1. Navigation Pane Quick Start Guide (Silverlight)
  2. How to build Office 2010 style Backstage application menu with DotNetBar for Windows Forms
  3. Rating Control for Silverlight Quick Start Guide
  4. Silverlight Toolbar Quick Start Guide
  5. Silverlight Schedule Control Quick Start Guide