Using Custom Controls

The wide array of controls described in the Bars Controls documentation should cover nearly all of the control types needed for use in ribbons, toolbars, and menus. In the event that the built-in controls don't fully meet your needs, custom controls can also be used.

An example is where you may wish to host some edit boxes from the Actipro Editors product like Int32EditBox within bars. Even though the edit box is an Actipro control, it wasn't made explicitly for use in bars and therefore is treated as a custom control for the purposes of this topic.

Attached Properties

The BarControlService class defines many attached properties that are reused across a number of bars controls. These properties are commonly assigned to custom controls:

Usage Contexts

RibbonGroup in a Classic Ribbon

If the custom control is hosted directly within a RibbonGroup, it will have a large height, roughly three times the height of small controls.

This kind of usage scenario is not typically recommended for custom controls except in special circumstances.

RibbonControlGroup in a Classic Ribbon

If the custom control is hosted in a RibbonControlGroup instead, it will use a small height if the control group is arranging children vertically. It's best to stick to a maximum control height that matches a native TextBox control height.

RibbonControlGroup instances in this scenario will attempt to render the small image and/or label of any child custom controls that are encountered, if the attached BarControlService.HasExternalHeaderProperty property is set to true. The attached BarControlService.SmallImageSourceProperty and LabelProperty set these UI values respectively.

xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars"
xmlns:editors="http://schemas.actiprosoftware.com/winfx/xaml/editors"
...
<bars:Ribbon>
	<bars:RibbonTabItem Key="Home">
		<bars:RibbonGroup Key="Range">
			<bars:RibbonControlGroup ItemVariantBehavior="AlwaysMedium">
				<editors:Int32EditBox
					bars:BarControlService.HasExternalHeader="True"
					bars:BarControlService.Key="Minimum"
					bars:BarControlService.Label="Minimum"
					bars:BarControlService.PanelSpacingSuggestion="Both"
					Width="60" MinHeight="24" MaxHeight="30"
					UsageContext="ToolBar"
					themes:ThemeProperties.CornerRadius="3"
					Value="{Binding MinimumValue, Mode=TwoWay}"
					/>
				...
			</bars:RibbonControlGroup>
		</bars:RibbonGroup>
		...
	</bars:RibbonTabItem>
</bars:StandaloneToolBar>

Simplified Ribbon

A custom control hosted within a Simplified ribbon will also use a small control height.

Ribbon Quick Access Toolbar (QAT)

A custom control can be cloned to the Quick Access Toolbar if the attached BarControlService.CanCloneToRibbonQuickAccessToolBarProperty is set to true on the custom control. Be aware that a custom control cloned to the QAT will use a small control height.

Toolbar

A custom control hosted within a toolbar will also use a small control height.

xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars"
xmlns:editors="http://schemas.actiprosoftware.com/winfx/xaml/editors"
...
<bars:StandaloneToolBar>
	<editors:Int32EditBox
		bars:BarControlService.HasExternalHeader="True"
		bars:BarControlService.Key="Minimum"
		bars:BarControlService.Label="Minimum"
		bars:BarControlService.PanelSpacingSuggestion="Both"
		Width="60" MinHeight="24" MaxHeight="30"
		UsageContext="ToolBar"
		themes:ThemeProperties.CornerRadius="3"
		Value="{Binding MinimumValue, Mode=TwoWay}"
		/>
	...
</bars:StandaloneToolBar>

Menu

Custom controls don't always work well in menu contexts, but a special BarMenuControlWrapper control is available to render an external label for a custom control and align everything with other neighboring menu items. This is great for controls like an edit box that don't render a label within their own template.

Bars menu controls will automatically wrap child controls that aren't flagged as menu controls with a BarMenuControlWrapper instance. A control can be flagged as a menu control by setting the BarControlService.IsMenuControlProperty attached property set to true.

The BarMenuControlWrapper control inherits native MenuItem but has a template that tailors it for hosting other custom controls. The custom control should be placed in the wrapper's BarMenuControlWrapper.Header property for proper display, which happens automatically if the custom control is within a Bars menu control.

xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars"
xmlns:editors="http://schemas.actiprosoftware.com/winfx/xaml/editors"
...
<bars:BarContextMenu>
	<editors:Int32EditBox
		bars:BarControlService.HasExternalHeader="True"
		bars:BarControlService.Key="Minimum"
		bars:BarControlService.Label="Minimum"
		bars:BarControlService.PanelSpacingSuggestion="Both"
		bars:BarControlService.SmallImageSource="/Images/Minimum16.png"
		Width="60" MinHeight="24" MaxHeight="30"
		UsageContext="ToolBar"
		themes:ThemeProperties.CornerRadius="3"
		Value="{Binding MinimumValue, Mode=TwoWay}"
		/>
	...
</bars:BarContextMenu>

When a label and/or small image are applied to a custom control with the attached LabelProperty and SmallImageSourceProperty properties, they will be displayed in the BarMenuControlWrapper alongside the custom control itself. The small image will align in the icon column with other menu items.

Screen Tips

The ScreenTip class inherits the native ToolTip control and therefore can be used anywhere a normal tooltip can, including on custom controls.

xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars"
xmlns:editors="http://schemas.actiprosoftware.com/winfx/xaml/editors"
...
<bars:StandaloneToolBar>
	<editors:Int32EditBox ... >
		<editors:Int32EditBox.ToolTip>
			<bars:ScreenTip Header="Maximum" Content="Specifies the range's maximum value." />
		</editors:Int32EditBox.ToolTip>
	</editors:Int32EditBox>
	...
</bars:StandaloneToolBar>

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