Control Basics

Many of the controls intended for use within ribbons, toolbars, and menus share some common characteristics and concepts. This topic reviews some of the core concepts for these controls.

Key

Each bar control has a string-based Key that is used to identify the control and allows it to be associated with other related controls anywhere in Bars control hierarchies. Label is meant for display purposes only and could be repeated on similar controls or even change from region to region when localizing the application, so the Key value should always be able to properly identify a control.

Examples

Here are several examples of Key values that could be used for various usage scenarios. These are just examples, and you are free to use any unique Key that you wish.

Usage Scenarios

The Key property is critical to supporting the following usage scenarios:

• Adding controls to the Quick Access Toolbar and detecting if a control has already been added.
• Serializing and deserializing the controls displayed in the Quick Access Toolbar.
• Explicitly defining control variant sizes when resizing the ribbon.
• Planned future functionality for UI customization.

Additionally, the Key property can also be used to optionally support the following features:

• Automatic generation of label and key tip when localization is not important.
• Automatically associate an image with a view model of the same Key when using MVVM.

Appearance

There are several appearance concepts that determine how the controls render.

Label

A Label is a text string that is usually visible within a control's user interface.

For example, a button's Label appears in the button's content, while a menu item's Label appears in the main text column of the menu item.

Examples of labels on a button and menu item

Label Auto-Generation

Controls that have both Key and Label properties will auto-generate a Label value based on the Key if no other Label has been specifically set.

It's recommended to either use "PascalCase" identifiers or hyphenated words when creating Key property values. Both Key values "AlignLeft" and "align-left" will auto-generate a Label value "Align Left".

This time-saving feature helps reduce the need to specify many Label values, except in scenarios where a customized value is necessary.

See the Label and Key Tip Generation topic for more information on auto-generated labels.

Images

Numerous controls display images in their user interface to better identify their function, sometimes without the use of a Label when trying to minimize size.

For example, a button's image appears in the button's content, and may be different sizes based on the button's variant size. A menu item's image appears in the icon column of the menu item.

Examples of various image sizes used when the control has a different variant size

Image Sizes

Some controls support a single image size, while other controls with variant sizes support multiple image sizes. These are the common image sizes:

Fallback Label and Images

If an image is not defined and is vital to the normal appearance of the control, a fallback display mechanism can occur, primarily in buttons.

In many cases, a missing image for small and medium variant size buttons will result in the label being displayed instead.

In other cases, such as when the control is within the ribbon's quick access toolbar or when the control is a collapsed ribbon group, then a default missing fallback image will be used.

The fallback image

The following table describes the priority order of properties (e.g., SmallImageSource, LargeImageSource) used to resolve an image for a desired image size.

Title

An optional string Title can be specified, which is intended to override the control's Label when displayed in screen tips and customization UI.

This is useful when you wish for a control to show a smaller label in UI, but the screen tip or customization UI should show a more verbose header.

Variant Sizes (Used in Ribbon)

Many controls support multiple variant sizes, where each variant alters the appearance of the control. As the variant size moves from larger to smaller, the change in appearance generally involves a reduction in the amount of information displayed in the control's content to save on overall space usage. Variant sizes are primarily utilized when a control is hosted within a ribbon.

As an example, examine a button's common variant size transitions within a Classic ribbon:

Several button variant size examples

Controls that support variant sizes have a VariantSize property that indicates the current variant size.

Some controls define a ToolBarItemVariantBehavior property that defaults to AlwaysSmall and indicates the variant sizes allowed when in a toolbar or Simplified ribbon. For instance, if a button should show an image and label in a Simplified ribbon when space is available, ToolBarItemVariantBehavior should be set to All, which allows small and medium variant sizes.

Some controls define a ToolBarItemOverflowBehavior property that defaults to Default and indicates how the control should handle possible overflow when in a Simplified ribbon. For instance, if a button should show always be overflowed in a Simplified ribbon, ToolBarItemOverflowBehavior should be set to Always.

See the Resizing and Variants topic for more information on variant sizes.

User Interface Density

Many controls support a user interface density option where values ranging from compact to spacious may be set to designate how much padding is used. Compact is best for more dense user interfaces where there is a need to display many controls at a time. Spacious is better for user interfaces with fewer controls that should be more touch-friendly. There also is a third option that strikes a balance between the other two.

See the Layout Modes and Density topic for more information on user interface density.

Key Tips

Key tips are small decorations that pop up over each control indicating a key or series of keys that may be typed to access the control via the keyboard. When a control's key tip text is typed, the control determines what action to take. Regular buttons may simulate a click, popup buttons may open a popup, and other controls may simply focus themselves and/or enter a new key tip scope.

Key tips active for a tab's scope

Controls that support key tips have a KeyTipText property that can be set to the string that should be typed to access the control while key tip mode is active.

See the Key Tips topic for more information on key tips.

Key Tip Auto-Generation

Most controls that have both Label and KeyTipText properties will auto-generate a KeyTipText value based on the Label if no other KeyTipText has been specifically set.

For example, a popup button's Label of "Table" will auto-generate a KeyTipText of "T", making it unnecessary to specify a KeyTipText.

This time-saving feature helps reduce the need to specify many KeyTipText values, except in scenarios where a customized value is necessary. Since most controls with a Key will auto-generate a Label, and Label will auto-generate KeyTipText, it is often only necessary to specify the Key and allow both the Label and KeyTipText to be auto-generated!

See the Label and Key Tip Generation topic for more information on auto-generated key tip text.

Commands and Events

Most controls have command support where the control's primary action executes the ICommand set in the control's Command property. Many times, the control will also raise an event when this primary action occurs.

For example, a regular button will execute its command and raise a Click event when the button is clicked or its key tip is accessed.

See the Using Commands topic for more information on commands.

Input Gesture Text

Input gestures are keyboard shortcuts that provide access to a control's command. For instance, Ctrl+C is commonly associated with the clipboard copy command.

Input gesture text is a textual representation of a keyboard shortcut, allowing the end user to learn which keyboard shortcut executes a command. Input gesture text is shown in screen tip headers and in menu items.

Controls that support the display of input gesture text have an InputGestureText property that can be set to any string (e.g., "Ctrl+Shift+T" or "Ctrl+V or Shift+Ins"). If an InputGestureText property value is not specified, screen tips and menu items will attempt to find a KeyGesture within the control's command. The command instance must be derived from RoutedCommand and have a KeyGesture assigned. The gesture's string representation will then be used as the input gesture text.

Input Gesture Text Visibility

Sometimes a control's input gesture text may be set to a value, but you don't wish for it to be visible in the user interface. Set the control's IsInputGestureTextVisible property to false to prevent it from showing in screen tips and menu items.

Screen Tips

Screen tips are advanced variations of standard tooltips that can display a header, input gesture text, extended description, complex content, and footer.

Most controls build their screen tip content using these properties:

• Label - Used in the screen tip header.
• Title - If specified, overrides the Label value displayed in the screen tip header.
• InputGestureText - When present, is displayed in the screen tip header, next to the content from Label or Title.
• ToolTip - If the native ToolTip property is set to a value that doesn't derive from the ToolTip class, it is used as the screen tip's extended description.

Several screen tip examples

For other more complex scenarios that need to display additional content, a ScreenTip instance with its various properties configured can be set to the native ToolTip property. It is generally recommended to use the properties listed above to ensure screen tips for all controls render in a consistent way.

See the Screen Tips topic for more information on screen tips.

MVVM Support

All of the Bars controls have been built from the ground up to support MVVM usage. An optional open source companion MVVM library is available that implements view models for each kind of control concept, and contains template selectors that generate the appropriate control view and all the appropriate view model bindings for each usage context.

As an example, when a ribbon configured with the library's template selectors encounters a BarButtonViewModel object within a ribbon group's items source, it will generate a BarButton control that is bound to the view model. On the other hand, if the BarButtonViewModel is located within a menu's items source, the template selector will generate a BarMenuItem control that is bound to the view model. This methodology enables the entire ribbon, toolbar, and menu hierarchy to be built and managed with view models.

While the open source companion MVVM library provides the most straightforward way to integrate MVVM concepts into Bars controls, it is not required, as there are no dependencies in Bars to any types in that MVVM library. Any configuration of custom view models and template selectors can be used instead if desired.

BarControlService Attached Properties

The BarControlService class defines numerous attached properties that are reused across many of the various Bars controls when appropriate.

Here is a list of common attached properties that are related to concepts described earlier in this topic:

Usage Scenarios

Use of the attached properties can sometimes make property retrieval much more efficient. Imagine that you wanted to get the Label of a control. You could build a large if statement like this:

string label = null;
if (control is BarButton barButton)
    label = barButton.Label;
else if (control is BarMenuItem barMenuItem)
    label = barMenuItem.Label;
else if ...  // More tests

Or you could use a single line like this:

var label = BarControlService.GetLabel(control);