From d4c2fc101596cfe1a85f2d539fa3a7965989e8ff Mon Sep 17 00:00:00 2001 From: Bill Henning Date: Tue, 17 Dec 2024 16:11:25 -0500 Subject: [PATCH] Updates for v24.1.4. --- Documentation/topics/bars/configuration.md | 8 +- .../topics/bars/controls/auto-generation.md | 17 +- Documentation/topics/bars/controls/button.md | 95 ++++++- .../topics/bars/controls/checkbox.md | 76 +++++- .../topics/bars/controls/combobox.md | 47 +++- .../topics/bars/controls/control-basics.md | 19 +- Documentation/topics/bars/controls/gallery.md | 181 ++++++++++++- Documentation/topics/bars/controls/heading.md | 34 ++- Documentation/topics/bars/controls/index.md | 11 +- .../topics/bars/controls/popup-button.md | 110 +++++++- .../topics/bars/controls/separator.md | 68 +++++ .../topics/bars/controls/split-button.md | 107 +++++++- Documentation/topics/bars/controls/textbox.md | 60 ++++- .../topics/bars/controls/using-commands.md | 28 ++- .../bars/controls/using-custom-controls.md | 96 ++++++- Documentation/topics/bars/getting-started.md | 67 ++++- Documentation/topics/bars/index.md | 2 + Documentation/topics/bars/localization.md | 14 ++ .../bars/menu-features/context-menus.md | 48 ++++ .../bars/menu-features/menu-customization.md | 4 +- Documentation/topics/bars/mvvm-support.md | 174 +++++++++++-- .../ribbon-features/application-button.md | 71 +++++- .../topics/bars/ribbon-features/backstage.md | 80 +++++- .../topics/bars/ribbon-features/collapsing.md | 15 ++ .../bars/ribbon-features/contextual-tabs.md | 60 +++++ .../bars/ribbon-features/control-hierarchy.md | 69 ++++- .../topics/bars/ribbon-features/footer.md | 94 ++++++- .../topics/bars/ribbon-features/index.md | 14 +- .../topics/bars/ribbon-features/key-tips.md | 11 + .../ribbon-features/layout-and-density.md | 9 +- .../bars/ribbon-features/options-button.md | 7 + .../ribbon-features/quick-access-toolbar.md | 42 ++++ .../bars/ribbon-features/recent-documents.md | 54 +++- .../topics/bars/ribbon-features/resizing.md | 238 +++++++++++++++++- .../bars/ribbon-features/screen-tips.md | 90 ++++++- .../bars/ribbon-features/serialization.md | 16 +- .../bars/ribbon-features/tab-row-toolbar.md | 34 ++- .../tabs-groups-controlgroups.md | 133 +++++++++- .../topics/bars/toolbar-features/index.md | 2 + .../toolbar-features/standalone-toolbars.md | 71 +++++- Documentation/topics/bars/troubleshooting.md | 12 +- .../docking-window-capabilities.md | 13 + .../floating-dock-hosts.md | 7 + Documentation/topics/licensing.md | 2 +- .../shared/windows-controls/avatar-group.md | 4 + .../PrismIntegration/PrismIntegration.csproj | 4 +- .../ActiproSoftware.References.props | 2 +- .../SampleMvvmControl.xaml.cs | 2 +- .../ComboBoxAndEditors/SampleXamlControl.xaml | 2 +- .../GalleryColorPickers/OptionsViewModel.cs | 15 ++ .../SampleXamlControl.xaml | 3 +- .../GalleryInRibbon/OptionsViewModel.cs | 17 +- .../GalleryInRibbon/SampleXamlControl.xaml | 3 +- .../GettingStarted/Step02/MainWindow.xaml | 4 +- .../GettingStarted/Step04/MainWindow.xaml | 2 +- .../GettingStarted/Step04/SampleBarManager.cs | 2 +- .../Step04/SampleWindowViewModel.cs | 2 +- .../GettingStarted/Step07/MainWindow.xaml | 8 +- .../GettingStarted/Step08/MainWindow.xaml | 2 +- .../CustomTreeListBoxItemAdapter.cs | 20 +- .../AvatarGroupIntro/MainControl.xaml | 2 + .../SampleBrowser/Properties/AssemblyInfo.cs | 4 +- .../SampleBrowser/Properties/Licenses.licx | 2 +- Samples/SampleBrowser/SampleBrowser.csproj | 2 +- .../Documents/ReleaseHistories/v24.1.xaml | 64 +++++ .../WindowsWorkflowIntegration.csproj | 6 +- Source/Bars.Mvvm/Bars.Mvvm.csproj | 4 +- .../Products/Bars.Mvvm/AssemblyInfo.cs | 4 +- .../BarControls/BarGalleryViewModel.cs | 15 ++ .../UI/Themes/BarsMvvmResourceDictionary.xaml | 2 + .../DataGrid.Contrib/DataGrid.Contrib.csproj | 4 +- .../Products/DataGrid/Contrib/AssemblyInfo.cs | 4 +- .../Editors.Interop.DataGrid.csproj | 4 +- .../Editors.Interop.DataGrid/AssemblyInfo.cs | 4 +- 74 files changed, 2456 insertions(+), 167 deletions(-) diff --git a/Documentation/topics/bars/configuration.md b/Documentation/topics/bars/configuration.md index 77c7ba1d..703cdb0a 100644 --- a/Documentation/topics/bars/configuration.md +++ b/Documentation/topics/bars/configuration.md @@ -12,11 +12,11 @@ All of the Bars controls have been built from the ground up to support both XAML ## XAML Configuration -All Bars controls can be defined directly in XAML and are designed to support common WPF usage scenarios like data binding. +All Bars controls can be defined directly in XAML and are designed to support common usage scenarios like data binding. ### Pros -XAML is familiar to most WPF developers and popular IDEs like Visual Studio provide designers that make it easy to visualize the run-time appearance of controls as their XAML is written. Newer IDEs even support hot reload of XAML definitions to modify a control at run-time and immediately see the impact of a change. Getting started with XAML can be very quick and the entire control definition can often be contained in a single file. +XAML is familiar to most @@PlatformTitle developers and popular IDEs like Visual Studio provide designers that make it easy to visualize the run-time appearance of controls as their XAML is written. Newer IDEs even support hot reload of XAML definitions to modify a control at run-time and immediately see the impact of a change. Getting started with XAML can be very quick and the entire control definition can often be contained in a single file. ### Cons @@ -24,7 +24,7 @@ Some controls are used in multiple locations, and using XAML will typically requ ## MVVM Configuration -MVVM is an extremely popular pattern used for WPF and one that is fully supported by Bars controls. +MVVM is an extremely popular pattern used for @@PlatformTitle and one that is fully supported by Bars controls. ### Pros @@ -39,7 +39,7 @@ In general, the MVVM pattern also has its own inherent benefits, like unit testi ### Cons -The MVVM pattern is naturally more complex than working directly in XAML and involves multiple view model classes, template selectors, styles, and other classes working together to achieve the desired result. Our companion [MVVM Library](mvvm-support.md) and extensive samples can get developers moving quickly, but configuring at least one central repository of view models for controls will be necessary. Testing design changes usually requires running the application since a visual designer may not be able to support the MVVM configuration at design-time. +The MVVM pattern is naturally more complex than working directly in XAML and involves multiple view model classes, template selectors, @if (avalonia) { themes, }@if (wpf) { styles, } and other classes working together to achieve the desired result. Our companion [MVVM Library](mvvm-support.md) and extensive samples can get developers moving quickly, but configuring at least one central repository of view models for controls will be necessary. Testing design changes usually requires running the application since a visual designer may not be able to support the MVVM configuration at design-time. Getting started with MVVM will typically take longer than XAML even if there are long-term efficiency gains. For simple projects, MVVM benefits may not be worth the extra effort. diff --git a/Documentation/topics/bars/controls/auto-generation.md b/Documentation/topics/bars/controls/auto-generation.md index ab74d9f9..4231d72a 100644 --- a/Documentation/topics/bars/controls/auto-generation.md +++ b/Documentation/topics/bars/controls/auto-generation.md @@ -7,7 +7,9 @@ order: 210 Many controls have `Key`, `Label`, and `KeyTipText` properties. Since these properties are closely related, controls can auto-generate a `Label` value based on the `Key` if no other `Label` has been explicitly set. Likewise, a `KeyTipText` value can be auto-generated from a `Label` if no other `KeyTipText` has been expicitly set. +@if (wpf) { Other contextual values (like certain `ICommand` types) can also be used when auto-generating property values. +} This time-saving feature helps reduce the need to specify many `Label` and `KeyTipText` values, except in scenarios where a customized value is necessary! @@ -48,13 +50,17 @@ Exception for the first word in "camelCase", all recognized words will use the c ### Label from Command +@if (avalonia) { +The default [LabelGenerator](xref:@ActiproUIRoot.Controls.Bars.LabelGenerator).[FromCommand](xref:@ActiproUIRoot.Controls.Bars.LabelGenerator.FromCommand*) method implementation will always return `null`, but this method can be overridden by derived classes to automatically provide labels for known commands. +} +@if (wpf) { The default [LabelGenerator](xref:@ActiproUIRoot.Controls.Bars.LabelGenerator).[FromCommand](xref:@ActiproUIRoot.Controls.Bars.LabelGenerator.FromCommand*) method implementation will analyze an `ICommand` to determine the best label. - The `ApplicationCommands.NotACommand` command is ignored and will always return a value of `null`. - Any other `RoutedUICommand` will use the `RoutedUICommand.Text` property as the label. - Any `RoutedCommand` will use the `RoutedCommand.Name` property as the label. - A value of `null` will be returned if a label could not be determined from the command. +} ## Key Tip Generation @@ -87,11 +93,16 @@ A value of `null` will be returned if a value for key tip text could not be dete ### Key Tip from Command +@if (avalonia) { +The default [KeyTipTextGenerator](xref:@ActiproUIRoot.Controls.Bars.KeyTipTextGenerator).[FromCommand](xref:@ActiproUIRoot.Controls.Bars.KeyTipTextGenerator.FromCommand*) method implementation will always return `null`, but this method can be overridden by derived classes to automatically provide key tips for known commands. +} +@if (wpf) { The default [KeyTipTextGenerator](xref:@ActiproUIRoot.Controls.Bars.KeyTipTextGenerator).[FromCommand](xref:@ActiproUIRoot.Controls.Bars.KeyTipTextGenerator.FromCommand*) method implementation will analyze an `ICommand` to determine the best key tip text. If the `ICommand` is a `RoutedCommand`, the `RoutedCommand.InputGestures` collection will be queried for gestures of type `KeyGesture`. The first `KeyGesture` that returns a non-`null` value when passed to [KeyTipTextGenerator](xref:@ActiproUIRoot.Controls.Bars.KeyTipTextGenerator).[FromKeyGesture](xref:@ActiproUIRoot.Controls.Bars.KeyTipTextGenerator.FromKeyGesture*) will be used as the key tip text. A value of `null` will be returned if a value for key tip text could not be determined from the `ICommand`. +} ## Localization @@ -105,7 +116,7 @@ The following steps can be used to implement localized label generation: 1. Create a new class that derives from [LabelGenerator](xref:@ActiproUIRoot.Controls.Bars.LabelGenerator). 1. Override the [LabelGenerator](xref:@ActiproUIRoot.Controls.Bars.LabelGenerator).[FromKey](xref:@ActiproUIRoot.Controls.Bars.LabelGenerator.FromKey*) method to return a localized label for the given key. -1. Optionally override the [LabelGenerator](xref:@ActiproUIRoot.Controls.Bars.LabelGenerator).[FromCommand](xref:@ActiproUIRoot.Controls.Bars.LabelGenerator.FromCommand*) method to return a localized label for the given command. This is only necessary if the `RoutedUICommand.Text` or `RoutedCommand.Name` properties are not already localized. +1. Optionally override the [LabelGenerator](xref:@ActiproUIRoot.Controls.Bars.LabelGenerator).[FromCommand](xref:@ActiproUIRoot.Controls.Bars.LabelGenerator.FromCommand*) method to return a localized label for the given command.@if (wpf) { This is only necessary if the `RoutedUICommand.Text` or `RoutedCommand.Name` properties are not already localized. } 1. During application startup before any UI is initialized, set the [BarControlService](xref:@ActiproUIRoot.Controls.Bars.BarControlService).[LabelGenerator](xref:@ActiproUIRoot.Controls.Bars.BarControlService.LabelGenerator) property to an instance of the custom class. > [!NOTE] @@ -119,7 +130,7 @@ The following steps can be used to implement localized key tip generation: 1. Create a new class that derives from [KeyTipTextGenerator](xref:@ActiproUIRoot.Controls.Bars.KeyTipTextGenerator). 1. Override the [KeyTipTextGenerator](xref:@ActiproUIRoot.Controls.Bars.KeyTipTextGenerator).[FromLabel](xref:@ActiproUIRoot.Controls.Bars.KeyTipTextGenerator.FromLabel*) method to return a localized key tip text for the given label. -1. Optionally override the [KeyTipTextGenerator](xref:@ActiproUIRoot.Controls.Bars.KeyTipTextGenerator).[FromCommand](xref:@ActiproUIRoot.Controls.Bars.KeyTipTextGenerator.FromCommand*) method to return a localized key tip text for the given command. This is only necessary if key tip text cannot be auto-generated from a `KeyGesture` defined within `RoutedCommand.InputGestures`. +1. Optionally override the [KeyTipTextGenerator](xref:@ActiproUIRoot.Controls.Bars.KeyTipTextGenerator).[FromCommand](xref:@ActiproUIRoot.Controls.Bars.KeyTipTextGenerator.FromCommand*) method to return a localized key tip text for the given command.@if (wpf) { This is only necessary if key tip text cannot be auto-generated from a `KeyGesture` defined within `RoutedCommand.InputGestures`. } 1. During application startup before any UI is initialized, set the [BarControlService](xref:@ActiproUIRoot.Controls.Bars.BarControlService).[KeyTipTextGenerator](xref:@ActiproUIRoot.Controls.Bars.BarControlService.KeyTipTextGenerator) property to an instance of the custom class. > [!NOTE] diff --git a/Documentation/topics/bars/controls/button.md b/Documentation/topics/bars/controls/button.md index a5960e56..d389cde6 100644 --- a/Documentation/topics/bars/controls/button.md +++ b/Documentation/topics/bars/controls/button.md @@ -26,6 +26,22 @@ If the button should be checkable, use the [BarToggleButton](xref:@ActiproUIRoot *BarButton examples in several variant sizes (large, medium, and small)* +@if (avalonia) { +| Specification | Details | +|-----|-----| +| Base class | Native `Button`. | +| Has key | Yes, via the [Key](xref:@ActiproUIRoot.Controls.Bars.BarButton.Key) property. | +| Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.BarButton.Label) property. Auto-generated from the `Key` value if not specified. | +| Has image | Yes, via the [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.SmallImageSource), [MediumImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.MediumImageSource), and [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.LargeImageSource) properties. | +| Has popup | No. | +| Is checkable | Yes, but only when using [BarToggleButton](xref:@ActiproUIRoot.Controls.Bars.BarToggleButton). | +| Variant sizes | `Small` (image only), `Medium` (image and label), `Large` (tall size, image and multi-line label). | +| Command support | Yes, via the `Command` property. | +| Key tip support | Yes, via the [KeyTipText](xref:@ActiproUIRoot.Controls.Bars.BarButton.KeyTipText) property. Auto-generated from the `Label` value if not specified. | +| [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarButton.CanCloneToRibbonQuickAccessToolBar) property. | +| [MVVM Library](../mvvm-support.md) VM | [BarButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarButtonViewModel) class for regular buttons, [BarToggleButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarToggleButtonViewModel) class for toggle buttons. | +} +@if (wpf) { | Specification | Details | |-----|-----| | Base class | Native `Button`. | @@ -40,7 +56,25 @@ If the button should be checkable, use the [BarToggleButton](xref:@ActiproUIRoot | [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarButton.CanCloneToRibbonQuickAccessToolBar) property. | | UI density support | Yes, via the [UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.BarButton.UserInterfaceDensity) property. | | [MVVM Library](../mvvm-support.md) VM | [BarButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarButtonViewModel) class for regular buttons, [BarToggleButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarToggleButtonViewModel) class for toggle buttons. | +} +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -55,6 +89,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ### Menu Contexts @@ -64,6 +99,22 @@ Use the [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) control to *A BarMenuItem example* +@if (avalonia) { +| Specification | Details | +|-----|-----| +| Base class | Native `MenuItem`. | +| Has key | Yes, via the [Key](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Key) property. | +| Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Label) property. Auto-generated from the `Key` value if not specified. | +| Has image | Yes, via the [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallImageSource) and [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeImageSource) properties. | +| Has popup | Not when a button concept is desired. | +| Is checkable | Yes, when the `ToggleType` property is set to `CheckBox` or `Radio`. | +| Variant sizes | None, but has a [UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.UseLargeSize) property that triggers a large height and displays an extended [Description](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Description). | +| Command support | Yes, via the `Command` property. | +| Key tip support | Yes, via the [KeyTipText](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.KeyTipText) property. Auto-generated from the `Label` value if not specified. | +| [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.CanCloneToRibbonQuickAccessToolBar) property. | +| [MVVM Library](../mvvm-support.md) VM | [BarButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarButtonViewModel) class for non-checkable menu items, [BarToggleButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarToggleButtonViewModel) class for checkable menu items. | +} +@if (wpf) { | Specification | Details | |-----|-----| | Base class | Native `MenuItem`. | @@ -78,7 +129,25 @@ Use the [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) control to | [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.CanCloneToRibbonQuickAccessToolBar) property. | | UI density support | None. | | [MVVM Library](../mvvm-support.md) VM | [BarButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarButtonViewModel) class for non-checkable menu items, [BarToggleButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarToggleButtonViewModel) class for checkable menu items. | +} +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -93,6 +162,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ## Appearance @@ -106,11 +176,20 @@ The `Label` can be auto-generated based on the control's `Key` property. For in The [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[Label](xref:@ActiproUIRoot.Controls.Bars.BarButton.Label) is rendered on the button when it is in a `Medium` or `Large` variant size. When using a `Large` variant size button, the label will wrap words to two lines to minimize overall width. In cases where a run of label text should not be broken up into two lines, use a non-breaking space character (ASCII code 160) in place of any whitespace, like this: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} The [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).[Label](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Label) is rendered on the menu item as its primary content. @@ -118,7 +197,7 @@ The [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).[Label](xref:@A The controls can display images that help identify their function. -All [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton) instances should set a [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.SmallImageSource) at a minimum, which is generally used for `Small` and `Medium` variants, as well as in the [Ribbon Quick Access Toolbar](../ribbon-features/quick-access-toolbar.md) and if the control overflows to a menu. If the button supports a `Large` variant size, it should also define a [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.LargeImageSource). When the button has a `Spacious` UI density, it will try to use [MediumImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.MediumImageSource). +All [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton) instances should set a [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.SmallImageSource) at a minimum, which is generally used for `Small` and `Medium` variants, as well as in the [Ribbon Quick Access Toolbar](../ribbon-features/quick-access-toolbar.md) and if the control overflows to a menu. If the button supports a `Large` variant size, it should also define a [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.LargeImageSource). @if (avalonia) { When the button is located on a ribbon with `Simplified` layout mode, }@if (wpf) { When the button has a `Spacious` UI density,} it will try to use [MediumImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.MediumImageSource). > [!TIP] > See the [Control Basics](control-basics.md) topic for more detail on the fallback logic for button images. @@ -143,9 +222,11 @@ While [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) doesn't suppo See the [Resizing and Variants](../ribbon-features/resizing.md) topic for more information on ribbon's variant sizing features. +@if (wpf) { ### User Interface Density (BarButton only) The [UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.BarButton.UserInterfaceDensity) property can alter the appearance of the button, such as its size, padding, and image used. This property is not generally set on the button instance itself, and is instead meant to be set on the root bar control to inherit down, such as with the [Ribbon.UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.Ribbon.UserInterfaceDensity) property. +} ### Checked State (BarToggleButton and BarMenuItem only) @@ -173,13 +254,19 @@ See the [Using Commands](using-commands.md) topic for more information on comman ## Input Gesture Text -The control can have input gesture text associated with it that describes a related keyboard shortcut, -and is displayed in the screen tip for the control or in the menu item itself. +The control can have input gesture text associated with it that describes a related keyboard shortcut, and is displayed in the screen tip for the control or in the menu item itself. + +@if (avalonia) { +Input gesture text can be specified in the [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[InputGesture](xref:@ActiproUIRoot.Controls.Bars.BarButton.InputGesture) and [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).`InputGesture` properties. +Input gesture text may be hidden altogether in UI by setting the [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[IsInputGestureTextVisible](xref:@ActiproUIRoot.Controls.Bars.BarButton.IsInputGestureTextVisible) and [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).[IsInputGestureTextVisible](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.IsInputGestureTextVisible) properties to `false`. +} +@if (wpf) { This input gesture text is automatically derived from commands that inherit `RoutedCommand` and have a `KeyGesture` set. Or input gesture text can be specified in the [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[InputGestureText](xref:@ActiproUIRoot.Controls.Bars.BarButton.InputGestureText) and [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).`InputGestureText` properties. Input gesture text may be hidden altogether in UI by setting the [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[IsInputGestureTextVisible](xref:@ActiproUIRoot.Controls.Bars.BarButton.IsInputGestureTextVisible) and [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).[IsInputGestureTextVisible](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.IsInputGestureTextVisible) properties to `false`. +} ## Screen Tips @@ -187,7 +274,7 @@ The controls support screen tips, which are formatted tool tips. The control's `Title` is used as the default screen tip header, falling back to `Label` if no `Title` is available. The [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[ScreenTipHeader](xref:@ActiproUIRoot.Controls.Bars.BarButton.ScreenTipHeader) and [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).[ScreenTipHeader](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.ScreenTipHeader) properties can override the default screen tip header value if desired. -If the control's `ToolTip` property is set to a value that doesn't derive from a native `ToolTip` control, such as a string, the value will be used in the screen tip's content area, with the screen tip header becoming bold. The screen tip's content area is where extended descriptions are displayed. +If the control's @if (avalonia) { `ToolTip.Tip` }@if (wpf) { `ToolTip` } property is set to a value that doesn't derive from a native `ToolTip` control, such as a string, the value will be used in the screen tip's content area, with the screen tip header becoming bold. The screen tip's content area is where extended descriptions are displayed. If the optional [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[ScreenTipFooter](xref:@ActiproUIRoot.Controls.Bars.BarButton.ScreenTipFooter) and [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).[ScreenTipFooter](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.ScreenTipFooter) properties are specified, they will appear in a footer area of the screen tip. diff --git a/Documentation/topics/bars/controls/checkbox.md b/Documentation/topics/bars/controls/checkbox.md index cbcfda31..a5063b00 100644 --- a/Documentation/topics/bars/controls/checkbox.md +++ b/Documentation/topics/bars/controls/checkbox.md @@ -22,6 +22,22 @@ Use the [BarCheckBox](xref:@ActiproUIRoot.Controls.Bars.BarCheckBox) control to *A BarCheckBox example* +@if (avalonia) { +| Specification | Details | +|-----|-----| +| Base class | [BarToggleButton](xref:@ActiproUIRoot.Controls.Bars.BarToggleButton), which indirectly inherits native `Button`. | +| Has key | Yes, via the [Key](xref:@ActiproUIRoot.Controls.Bars.BarButton.Key) property. | +| Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.BarButton.Label) property. Auto-generated from the `Key` value if not specified. | +| Has image | No. | +| Has popup | No. | +| Is checkable | Yes. | +| Variant sizes | None. | +| Command support | Yes, via the `Command` property. | +| Key tip support | Yes, via the [KeyTipText](xref:@ActiproUIRoot.Controls.Bars.BarButton.KeyTipText) property. Auto-generated from the `Label` value if not specified. | +| [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarButton.CanCloneToRibbonQuickAccessToolBar) property. | +| [MVVM Library](../mvvm-support.md) VM | [BarCheckBoxViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarCheckBoxViewModel) class. | +} +@if (wpf) { | Specification | Details | |-----|-----| | Base class | [BarToggleButton](xref:@ActiproUIRoot.Controls.Bars.BarToggleButton), which indirectly inherits native `Button`. | @@ -36,7 +52,23 @@ Use the [BarCheckBox](xref:@ActiproUIRoot.Controls.Bars.BarCheckBox) control to | [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarButton.CanCloneToRibbonQuickAccessToolBar) property. | | UI density support | None. | | [MVVM Library](../mvvm-support.md) VM | [BarCheckBoxViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarCheckBoxViewModel) class. | +} +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -49,6 +81,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ### Menu Contexts @@ -56,8 +89,24 @@ Use the [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) control to ![Screenshot](../images/checkbox-menu.png) -*A BarMenuItem example* +*A checkable BarMenuItem example in checked state* +@if (avalonia) { +| Specification | Details | +|-----|-----| +| Base class | Native `MenuItem`. | +| Has key | Yes, via the [Key](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Key) property. | +| Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Label) property. Auto-generated from the `Key` value if not specified. | +| Has image | Yes, via the [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallImageSource) and [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeImageSource) properties. | +| Has popup | Not when a checkbox concept is desired. | +| Is checkable | Yes, when the `ToggleType` property is set to `CheckBox` or `Radio`. | +| Variant sizes | None, but has a [UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.UseLargeSize) property that triggers a large height and displays an extended [Description](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Description). | +| Command support | Yes, via the `Command` property. | +| Key tip support | Yes, via the [KeyTipText](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.KeyTipText) property. Auto-generated from the `Label` value if not specified. | +| [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.CanCloneToRibbonQuickAccessToolBar) property. | +| [MVVM Library](../mvvm-support.md) VM | [BarCheckBoxViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarCheckBoxViewModel) class. | +} +@if (wpf) { | Specification | Details | |-----|-----| | Base class | Native `MenuItem`. | @@ -72,7 +121,24 @@ Use the [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) control to | [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.CanCloneToRibbonQuickAccessToolBar) property. | | UI density support | None. | | [MVVM Library](../mvvm-support.md) VM | [BarCheckBoxViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarCheckBoxViewModel) class. | +} +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -86,6 +152,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ## Appearance @@ -150,8 +217,13 @@ See the [Using Commands](using-commands.md) topic for more information on comman The control can have input gesture text associated with it that describes a related keyboard shortcut, and is displayed in the screen tip for the control or in the menu item itself. +@if (avalonia) { +Input gesture text can be specified in the [BarCheckBox](xref:@ActiproUIRoot.Controls.Bars.BarCheckBox).[InputGesture](xref:@ActiproUIRoot.Controls.Bars.BarButton.InputGesture) and [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).`InputGesture` properties. +} +@if (wpf) { This input gesture text is automatically derived from commands that inherit `RoutedCommand` and have a `KeyGesture` set. Or input gesture text can be specified in the [BarCheckBox](xref:@ActiproUIRoot.Controls.Bars.BarCheckBox).[InputGestureText](xref:@ActiproUIRoot.Controls.Bars.BarButton.InputGestureText) and [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).`InputGestureText` properties. +} Input gesture text may be hidden altogether in UI by setting the [BarCheckBox](xref:@ActiproUIRoot.Controls.Bars.BarCheckBox).[IsInputGestureTextVisible](xref:@ActiproUIRoot.Controls.Bars.BarButton.IsInputGestureTextVisible) and [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).[IsInputGestureTextVisible](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.IsInputGestureTextVisible) properties to `false`. @@ -161,7 +233,7 @@ The controls support screen tips, which are formatted tool tips. The control's `Title` is used as the default screen tip header, falling back to `Label` if no `Title` is available. The [BarCheckBox](xref:@ActiproUIRoot.Controls.Bars.BarCheckBox).[ScreenTipHeader](xref:@ActiproUIRoot.Controls.Bars.BarButton.ScreenTipHeader) and [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).[ScreenTipHeader](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.ScreenTipHeader) properties can override the default screen tip header value if desired. -If the control's `ToolTip` property is set to a value that doesn't derive from a native `ToolTip` control, such as a string, the value will be used in the screen tip's content area, with the screen tip header becoming bold. The screen tip's content area is where extended descriptions are displayed. +If the control's @if (avalonia) { `ToolTip.Tip` }@if (wpf) { `ToolTip` } property is set to a value that doesn't derive from a native `ToolTip` control, such as a string, the value will be used in the screen tip's content area, with the screen tip header becoming bold. The screen tip's content area is where extended descriptions are displayed. If the optional [BarCheckBox](xref:@ActiproUIRoot.Controls.Bars.BarCheckBox).[ScreenTipFooter](xref:@ActiproUIRoot.Controls.Bars.BarButton.ScreenTipFooter) and [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).[ScreenTipFooter](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.ScreenTipFooter) properties are specified, they will appear in a footer area of the screen tip. diff --git a/Documentation/topics/bars/controls/combobox.md b/Documentation/topics/bars/controls/combobox.md index a44365cf..bff2b529 100644 --- a/Documentation/topics/bars/controls/combobox.md +++ b/Documentation/topics/bars/controls/combobox.md @@ -26,6 +26,22 @@ In summary, a [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery) *A BarComboBox example* +@if (avalonia) { +| Specification | Details | +|-----|-----| +| Base class | [BarMenuGalleryHostBase](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuGalleryHostBase), which indirectly inherits native `Selector`. | +| Has key | Yes, via the [Key](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.Key) property. | +| Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.Label) property. Auto-generated from the `Key` value if not specified. | +| Has image | Yes, inline via the [InlineImageSourcePath](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.InlineImageSourcePath) property or externally via the [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.SmallImageSource) property. | +| Has popup | Yes, which shows a [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery) with the same items, and optionally additional menu items. | +| Is checkable | No. | +| Variant sizes | None. | +| Command support | Yes, via the [Command](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.Command) and [UnmatchedTextCommand](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.UnmatchedTextCommand) properties. | +| Key tip support | Yes, via the [KeyTipText](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.KeyTipText) property. Auto-generated from the `Label` value if not specified. | +| [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.CanCloneToRibbonQuickAccessToolBar) property. | +| [MVVM Library](../mvvm-support.md) VM | [BarComboBoxViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarComboBoxViewModel) class. | +} +@if (wpf) { | Specification | Details | |-----|-----| | Base class | [BarMenuGalleryHostBase](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuGalleryHostBase), which indirectly inherits native `Selector`. | @@ -40,7 +56,33 @@ In summary, a [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery) | [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.CanCloneToRibbonQuickAccessToolBar) property. | | UI density support | None. | | [MVVM Library](../mvvm-support.md) VM | [BarComboBoxViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarComboBoxViewModel) class. | +} +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" xmlns:themes="http://schemas.actiprosoftware.com/winfx/xaml/themes" @@ -65,9 +107,10 @@ xmlns:themes="http://schemas.actiprosoftware.com/winfx/xaml/themes" ... ``` +} > [!IMPORTANT] -> When defining a `BarComboBox` in XAML and binding the items source to instances of [IBarGalleryItemViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.IBarGalleryItemViewModel) from the [MVVM Library](../mvvm-support.md), the `ItemContainerStyle` must be defined as shown in the sample above to establish important bindings between [IBarGalleryItemViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.IBarGalleryItemViewModel) and [BarGalleryItem](xref:@ActiproUIRoot.Controls.Bars.BarGalleryItem). +> When defining a `BarComboBox` in XAML and binding the items source to instances of [IBarGalleryItemViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.IBarGalleryItemViewModel) from the [MVVM Library](../mvvm-support.md), the @if (avalonia) { `ItemContainerTheme` }@if (wpf) { `ItemContainerStyle` } must be defined as shown in the sample above to establish important bindings between [IBarGalleryItemViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.IBarGalleryItemViewModel) and [BarGalleryItem](xref:@ActiproUIRoot.Controls.Bars.BarGalleryItem). ### Menu Contexts @@ -180,7 +223,7 @@ The controls support screen tips, which are formatted tool tips. The control's `Title` is used as the default screen tip header, falling back to `Label` if no `Title` is available. The [ScreenTipHeader](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.ScreenTipHeader) property can override the default screen tip header value if desired. -If the control's `ToolTip` property is set to a value that doesn't derive from a native `ToolTip` control, such as a string, the value will be used in the screen tip's content area, with the screen tip header becoming bold. The screen tip's content area is where extended descriptions are displayed. +If the control's @if (avalonia) { `ToolTip.Tip` }@if (wpf) { `ToolTip` } property is set to a value that doesn't derive from a native `ToolTip` control, such as a string, the value will be used in the screen tip's content area, with the screen tip header becoming bold. The screen tip's content area is where extended descriptions are displayed. If the optional [ScreenTipFooter](xref:@ActiproUIRoot.Controls.Bars.BarComboBox.ScreenTipFooter) property is specified, it will appear in a footer area of the screen tip. diff --git a/Documentation/topics/bars/controls/control-basics.md b/Documentation/topics/bars/controls/control-basics.md index 6306c871..7e7c58ff 100644 --- a/Documentation/topics/bars/controls/control-basics.md +++ b/Documentation/topics/bars/controls/control-basics.md @@ -144,11 +144,13 @@ Some controls define a `ToolBarItemOverflowBehavior` property that defaults to ` See the [Resizing and Variants](../ribbon-features/resizing.md) topic for more information on variant sizes. +@if (wpf) { ### 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](../ribbon-features/layout-and-density.md) topic for more information on user interface density. +} ## Key Tips @@ -186,7 +188,12 @@ Input gestures are keyboard shortcuts that provide access to a control's 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. +@if (avalonia) { +Controls that support the display of input gesture text have an `InputGesture` property that can be set to strings which parse as a `KeyGesture` (e.g., `"Ctrl+Shift+T"`). The gesture's string representation will then be used as the input gesture text. +} +@if (wpf) { 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 @@ -198,16 +205,24 @@ Screen tips are advanced variations of standard tooltips that can display a head Most controls build their screen tip content using these properties: +@if (avalonia) { +- `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.Tip` - If the native `ToolTip.Tip` property is set to a value that doesn't derive from the `ToolTip` class, it is used as the screen tip's extended description. +} +@if (wpf) { - `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. +} ![Screenshot](../images/screen-tips.png) *Several screen tip examples* -For other more complex scenarios that need to display additional content, a [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.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. +For other more complex scenarios that need to display additional content, a [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip) instance with its various properties configured can be set to the native @if (avalonia) { `ToolTip.Tip` }@if (wpf) { `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](../ribbon-features/screen-tips.md) topic for more information on screen tips. @@ -220,7 +235,7 @@ As an example, when a ribbon configured with the library's template selectors en > [!TIP] > See the [MVVM Support](../mvvm-support.md) topic for more information on MVVM support and the pre-built MVVM library of view models and template selectors designed for Bars controls. -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. +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. If desired, any configuration of custom view models and template selectors can be used instead. ## BarControlService Attached Properties diff --git a/Documentation/topics/bars/controls/gallery.md b/Documentation/topics/bars/controls/gallery.md index 586adbb6..9c33c936 100644 --- a/Documentation/topics/bars/controls/gallery.md +++ b/Documentation/topics/bars/controls/gallery.md @@ -29,6 +29,22 @@ Use the [RibbonGallery](xref:@ActiproUIRoot.Controls.Bars.RibbonGallery) control *An in-ribbon gallery* +@if (avalonia) { +| Specification | Details | +|-----|-----| +| Base class | [BarMenuGalleryHostBase](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuGalleryHostBase), which indirectly inherits native `Selector`. | +| Has key | Yes, via the [Key](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.Key) property. | +| Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.Label) property. Auto-generated from the `Key` value if not specified. | +| Has image | Yes, via the [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.SmallImageSource), [MediumImageSource](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.MediumImageSource), and [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.LargeImageSource) properties. | +| Has popup | Yes, which shows a [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery) with the same items, and optionally additional menu items. | +| Is checkable | No. | +| Variant sizes | `Small` (collapsed gallery popup button), `Medium` (several columns), `Large` (many columns). | +| Command support | Yes, via the [Command](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.Command) property. The gallery item that is selected/previewed is passed as the command parameter. | +| Key tip support | Yes, via the [KeyTipText](xref:@ActiproUIRoot.Controls.Bars.RibbonGallery.KeyTipText) property, for the `More` button when expanded and the collapsed gallery popup button. Auto-generated from the `Label` value if not specified. | +| [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.CanCloneToRibbonQuickAccessToolBar) property. | +| [MVVM Library](../mvvm-support.md) VM | [BarGalleryViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryViewModel) class. | +} +@if (wpf) { | Specification | Details | |-----|-----| | Base class | [BarMenuGalleryHostBase](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuGalleryHostBase), which indirectly inherits native `Selector`. | @@ -43,7 +59,44 @@ Use the [RibbonGallery](xref:@ActiproUIRoot.Controls.Bars.RibbonGallery) control | [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.CanCloneToRibbonQuickAccessToolBar) property. | | UI density support | Yes, via the [UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.UserInterfaceDensity) property. | | [MVVM Library](../mvvm-support.md) VM | [BarGalleryViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryViewModel) class. | +} +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + +... + + + + + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" xmlns:themes="http://schemas.actiprosoftware.com/winfx/xaml/themes" @@ -78,11 +131,32 @@ xmlns:themes="http://schemas.actiprosoftware.com/winfx/xaml/themes" ... ``` +} ### Ribbon and Toolbar Contexts Galleries can be used in other ways within a ribbon, and in toolbar contexts as well. This is supported by placing a [Popup Button](popup-button.md) or [Split Button](split-button.md) in the toolbar and then using a [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery) control (described below) in the popup menu. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + ... + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -100,6 +174,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ``` +} ### Menu Contexts @@ -109,6 +184,22 @@ Use the [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery) contr *A list numbering gallery* +@if (avalonia) { +| Specification | Details | +|-----|-----| +| Base class | [BarGalleryBase](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase), which inherits native `Selector`. | +| Has key | Yes, via the [Key](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.Key) property. | +| Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.Label) property. Auto-generated from the `Key` value if not specified. | +| Has image | No. | +| Has popup | No. | +| Is checkable | No. | +| Variant sizes | None. | +| Command support | Yes, via the [Command](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.Command) property. The gallery item that is selected/previewed is passed as the command parameter. | +| Key tip support | None. | +| [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Not directly. Ribbon logic will look for a containing [Popup Button](popup-button.md) or [Split Button](split-button.md) to clone to the Quick Access Toolbar instead. | +| [MVVM Library](../mvvm-support.md) VM | [BarGalleryViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryViewModel) class. | +} +@if (wpf) { | Specification | Details | |-----|-----| | Base class | [BarGalleryBase](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase), which inherits native `Selector`. | @@ -123,7 +214,26 @@ Use the [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery) contr | [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Not directly. Ribbon logic will look for a containing [Popup Button](popup-button.md) or [Split Button](split-button.md) to clone to the Quick Access Toolbar instead. | | UI density support | None. | | [MVVM Library](../mvvm-support.md) VM | [BarGalleryViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryViewModel) class. | +} +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -139,6 +249,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ## Appearance @@ -262,9 +373,11 @@ When a gallery is solely presented within the menu of a containing [Popup Button This feature can be enabled by setting the [RibbonGallery](xref:@ActiproUIRoot.Controls.Bars.RibbonGallery).[UseMenuItemAppearance](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuGalleryHostBase.UseMenuItemAppearance) or [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery).[UseMenuItemAppearance](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery.UseMenuItemAppearance) property to `true`. It is recommended to restrict the gallery to a single column when using this feature. The "Columns Displayed on Menu" section above explains how to restrict the column count. +@if (wpf) { ### User Interface Density (RibbonGallery only) The [UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.UserInterfaceDensity) property can alter the appearance of the gallery, such as its size and padding used. This property is not generally set on the gallery instance itself, and is instead meant to be set on the root bar control to inherit down, such as with the [Ribbon.UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.Ribbon.UserInterfaceDensity) property. +} ## Key Tips @@ -298,7 +411,7 @@ This view model class maps over to the appropriate view controls described above A [IBarGalleryItemViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.IBarGalleryItemViewModel) interface defines the common requirements for gallery item view models, and a [BarGalleryItemViewModel\](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryItemViewModel`1) class is intended to be used directly, or as a base class for any gallery item view model. Each kind of gallery should define a separate view model class for its items. For instance, a gallery related to selection of a color defines a [ColorBarGalleryItemViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.ColorBarGalleryItemViewModel) class for its items, which inherits [BarGalleryItemViewModel\](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryItemViewModel`1). -It is recommended to build a custom `DataTemplateSelector` that can be assigned to the gallery's `ItemTemplateSelector` property to apply a `DataTemplate` for the related gallery item view model type. +It is recommended to build a custom @if (avalonia) { `IDataTemplateSelector` }@if (wpf) { `DataTemplateSelector` } that can be assigned to the gallery's `ItemTemplateSelector` property to apply @if (avalonia) { an `IDataTemplate` }@if (wpf) { a `DataTemplate` } for the related gallery item view model type. > [!TIP] > See the [MVVM Support](../mvvm-support.md) topic for more information on how to use the library's view models and view templates to create and manage your application's bars controls with MVVM techniques. @@ -311,8 +424,14 @@ Gallery items are often very visual in nature. Some galleries maintain a select It is recommended to always use custom view model types for gallery items, and to bind an enumerable of view model instances to the gallery's `ItemsSource` property. +@if (avalonia) { +> [!NOTE] +> If gallery categorizing or filtering support is desired, an [ICollectionView](xref:@ActiproUIRoot.Data.ICollectionView) instance must be bound to the gallery's `ItemsSource` property. The [ICollectionView](xref:@ActiproUIRoot.Data.ICollectionView).[Groups](xref:@ActiproUIRoot.Data.ICollectionView.Groups) collection should have a [CollectionViewGroup](xref:@ActiproUIRoot.Data.CollectionViewGroup) added to it that defines the category name to be used for each gallery item view model instance. See the "Item Categorization" section below for more information. +} +@if (wpf) { > [!NOTE] > If gallery categorizing or filtering support is desired, an `ICollectionView` instance must be bound to the gallery's `ItemsSource` property. The `ICollectionView.GroupDescriptions` collection should have a `PropertyGroupDescription` added to it that specifies the name of the category property on the gallery item view model `Type`. See the "Item Categorization" section below for more information. +} > [!CAUTION] > There are several scenarios where multiple gallery controls may be created for the same conceptual set of gallery items. For instance, the [RibbonGallery](xref:@ActiproUIRoot.Controls.Bars.RibbonGallery) control has an implicitly created [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery) that appears in its **More** button's popup menu, and the [BarComboBox](xref:@ActiproUIRoot.Controls.Bars.BarComboBox) control has an implicitly-created [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery) that appears in its drop-down menu. Galleries may also be cloned to the [Quick Access Toolbar](../ribbon-features/quick-access-toolbar.md) or cloned for overflow purposes. @@ -335,27 +454,45 @@ The [RibbonGallery](xref:@ActiproUIRoot.Controls.Bars.RibbonGallery).[CanAutoScr Gallery controls generate a [BarGalleryItem](xref:@ActiproUIRoot.Controls.Bars.BarGalleryItem) container for each gallery item in the gallery's `ItemsSource`. -A `DataTemplate` for the view model type can be supplied via the [BarGalleryBase](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase).`ItemTemplate` property, or alternatively, a `DataTemplateSelector`-based class instance can be set to the gallery's `ItemTemplateSelector` property. These concepts are all fundamental to how any data-bound `ItemsControl` works. +A `DataTemplate` for the view model type can be supplied via the [BarGalleryBase](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase).`ItemTemplate` property, or alternatively, @if (avalonia) { an `IDataTemplateSelector`-based }@if (wpf) { a `DataTemplateSelector`-based } class instance can be set to the gallery's `ItemTemplateSelector` property. These concepts are all fundamental to how any data-bound `ItemsControl` works. Any UI elements can be placed in a `DataTemplate`, allowing you to make your gallery items' appearance as simple or complex as you wish. Here's an example of a template for a font size view model that has a `FontSize` property and uses a basic `TextBlock` for display. +@if (avalonia) { +```xaml + + + +``` +} +@if (wpf) { ```xaml ``` +} Note that no borders are usually necessary in a gallery item template since the containing [BarGalleryItem](xref:@ActiproUIRoot.Controls.Bars.BarGalleryItem) will render the chrome of the item. In the following example for an insert symbol gallery, we use a custom `SymbolPresenter` element. This element could be a custom templated `Control` itself. Or it could be a more basic element that overrides its `OnRender` method to render the content in code-behind via a `DrawingContext`. +@if (avalonia) { +```xaml + + + +``` +} +@if (wpf) { ```xaml ``` +} While the template examples above only contain a single element, any complex element hierarchy can be placed within the template to achieve the look you desire. @@ -403,7 +540,7 @@ The [BarGalleryItem](xref:@ActiproUIRoot.Controls.Bars.BarGalleryItem).[Label](x It doesn't make sense for galleries that show a label within the item itself to also display a tooltip containing simple label content. For instance, a font size gallery shows the font size number, which is the label, in each gallery item. Having a tooltip that would show the same value is not helpful. For cases like this, set the attached [BarControlService](xref:@ActiproUIRoot.Controls.Bars.BarControlService).[IsLabelVisibleProperty](xref:@ActiproUIRoot.Controls.Bars.BarControlService.IsLabelVisibleProperty) property to `true` on [BarGalleryItem](xref:@ActiproUIRoot.Controls.Bars.BarGalleryItem). If you are using the [MVVM Library](../mvvm-support.md), have the [BarGalleryItemViewModel\](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryItemViewModel`1).[IsLabelVisible](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryItemViewModel`1.IsLabelVisible) property return `true`, which will bind over to the attached property that prevents a simple tooltip from showing. -Set the [BarGalleryItem](xref:@ActiproUIRoot.Controls.Bars.BarGalleryItem).`ToolTip` property to a string to add an extended description for a gallery item. Alternatively, the value may be any `ToolTip`-derived class, including our [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip) class. +Set the @if (avalonia) { [BarGalleryItem](xref:@ActiproUIRoot.Controls.Bars.BarGalleryItem).`ToolTip.Tip` }@if (wpf) { [BarGalleryItem](xref:@ActiproUIRoot.Controls.Bars.BarGalleryItem).`ToolTip` } property to a string to add an extended description for a gallery item. Alternatively, the value may be any `ToolTip`-derived class, including our [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip) class. ### Item Categorization @@ -413,6 +550,23 @@ Gallery items can be placed in categories. These categories will not show up in *A color picker gallery with categorized colors* +@if (avalonia) { +Menu gallery categorization requires that the gallery item view model collection is bound to the [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery).`ItemsSource` property, and the collection must be an [ICollectionView](xref:@ActiproUIRoot.Data.ICollectionView). The [ICollectionView](xref:@ActiproUIRoot.Data.ICollectionView).[Groups](xref:@ActiproUIRoot.Data.ICollectionView.Groups) collection must have a [CollectionViewGroup](xref:@ActiproUIRoot.Data.CollectionViewGroup) added to it that defines the category name to be used for each gallery item view model instance. For instance, if using gallery item view models from our [MVVM Library](../mvvm-support.md), the category can be returned from the [IBarGalleryItemViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.IBarGalleryItemViewModel).[Category](xref:@ActiproUIRoot.Controls.Bars.Mvvm.IBarGalleryItemViewModel.Category) property. + +Here is a helper method on [BarGalleryViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryViewModel) that shows how to set up an [ICollectionView](xref:@ActiproUIRoot.Data.ICollectionView) for categorizing a collection of gallery items: + +```csharp +public static ICollectionView CreateCollectionView(IEnumerable items, bool categorize) { + var collectionView = new CollectionView(items); + + if (categorize) + collectionView.GroupDescriptions.Add(new GroupDescription(x => x.Category)); + + return collectionView; +} +``` +} +@if (wpf) { Menu gallery categorization requires that the gallery item view model collection is bound to the [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery).`ItemsSource` property, and the collection must be an `ICollectionView`. The `ICollectionView.GroupDescriptions` collection must have a `PropertyGroupDescription` added to it that specifies the name of the category property on the gallery item view model `Type`. For instance, if using gallery item view models from our [MVVM Library](../mvvm-support.md), the category property there is [IBarGalleryItemViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.IBarGalleryItemViewModel).[Category](xref:@ActiproUIRoot.Controls.Bars.Mvvm.IBarGalleryItemViewModel.Category) so a `PropertyGroupDescription` would specify `"Category"`. Here is a helper method on [BarGalleryViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryViewModel) that shows how to set up an `ICollectionView` for categorizing a collection of gallery items: @@ -428,8 +582,9 @@ public static ICollectionView CreateCollectionView(IEnumerable [!WARNING] +> The [ICollectionView](xref:@ActiproUIRoot.Data.ICollectionView) interface and related types are experimental implementations used to support grouping and filtering in Avalonia since `ItemsControl` does not natively support the functionality. While they are public classes from the Shared Library, they are subject to breaking changes and should only be used as directed when working with Bars controls. These types may be removed in a future release if `ItemsControl` implements the necessary native support. +} + ### Categorized Item Filtering (BarMenuGallery only) If you have categorization enabled in your [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery) as described above, you can optionally add filtering capabilities. The filter is a button at the top of the gallery that, when clicked, shows a menu of available filters for selection. @@ -455,6 +615,18 @@ Set the [RibbonGallery](xref:@ActiproUIRoot.Controls.Bars.RibbonGallery).[CanFil [RibbonGallery](xref:@ActiproUIRoot.Controls.Bars.RibbonGallery) has the ability to display additional menu items above or below the menu gallery on its **More** button's popup menu. This can be achieved by adding menu items into its [AboveMenuItems](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuGalleryHostBase.AboveMenuItems) and [BelowMenuItems](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuGalleryHostBase.BelowMenuItems) collections. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -464,6 +636,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ``` +} ## Size Selection Menu Gallery diff --git a/Documentation/topics/bars/controls/heading.md b/Documentation/topics/bars/controls/heading.md index 2561e387..3a4f548b 100644 --- a/Documentation/topics/bars/controls/heading.md +++ b/Documentation/topics/bars/controls/heading.md @@ -26,6 +26,22 @@ Use the [BarMenuHeading](xref:@ActiproUIRoot.Controls.Bars.BarMenuHeading) contr *A heading at the top of a menu* +@if (avalonia) { +| Specification | Details | +|-----|-----| +| Base class | Native `Separator`. | +| Has key | No. | +| Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.BarMenuHeading.Label) property. | +| Has image | No. | +| Has popup | No. | +| Is checkable | No. | +| Variant sizes | None. | +| Command support | None. | +| Key tip support | None. | +| [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | None. | +| [MVVM Library](../mvvm-support.md) VM | [BarHeadingViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarHeadingViewModel) class. | +} +@if (wpf) { | Specification | Details | |-----|-----| | Base class | Native `MenuItem`. | @@ -40,18 +56,34 @@ Use the [BarMenuHeading](xref:@ActiproUIRoot.Controls.Bars.BarMenuHeading) contr | [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | None. | | UI density support | None. | | [MVVM Library](../mvvm-support.md) VM | [BarHeadingViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarHeadingViewModel) class. | +} +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... - + ... ``` +} ## MVVM Support diff --git a/Documentation/topics/bars/controls/index.md b/Documentation/topics/bars/controls/index.md index 2c7e8cd4..6afc0428 100644 --- a/Documentation/topics/bars/controls/index.md +++ b/Documentation/topics/bars/controls/index.md @@ -17,7 +17,7 @@ These subjects and others are discussed in the [Control Basics](control-basics.m The built-in controls documentation is organized by control concept. There are often multiple controls that implement a certain concept, one for each context where that control concept should be used. -For instance, a regular button concept described in the [Button](button.md) topic is implemented by a [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton) control for use in ribbons and toolbars, and a [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) control for use in menus. Each topic below explains details on the control classes involved in implementation of the related control concept. +For instance, a regular button concept described in the [Button](button.md) topic is implemented by a [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton) control for use in ribbons and toolbars, and a [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) control for use in menus. Each topic below explains details on the control classes involved in the implementation of the related control concept. @@ -180,7 +180,7 @@ Implemented as a separator bar in ribbons, toolbars, and menus. ## Using Commands -All interactive controls in this product are designed to work well with MVVM patterns and the WPF command model. +All interactive controls in this product are designed to work well with MVVM patterns and the @@PlatformTitle command model. Controls will execute their command when a primary action occurs on the control and use the command's can-execute result to determine if the control is enabled. Commands can be used to support live preview of gallery items as well. @@ -190,7 +190,12 @@ See the [Using Commands](using-commands.md) topic for more information. The wide array of controls described above should cover nearly all the control types needed for use in ribbons, toolbars, and menus. If the built-in controls don't fully meet your needs, custom controls can also be used. +@if (avalonia) { +An example is where you may wish to host some native editors, like `NumericUpDown` or `CalendarDatePicker`, within bars. +} +@if (wpf) { An example is where you may wish to host some edit boxes from the [Actipro Editors](../../editors/index.md) product like [Int32EditBox](../../editors/editboxes/int32editbox.md) 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. +} See the [Using Custom Controls](using-custom-controls.md) topic for more information. @@ -198,7 +203,9 @@ See the [Using Custom Controls](using-custom-controls.md) topic for more informa Many controls have `Key`, `Label`, and `KeyTipText` properties. Since these properties are closely related, controls can auto-generate a `Label` value based on the `Key` if no other `Label` has been explicitly set. Likewise, a `KeyTipText` value can be auto-generated from a `Label` if no other `KeyTipText` has been expicitly set. +@if (wpf) { Other contextual values (like certain `ICommand` types) can also be used when auto-generating property values. +} This time-saving feature helps reduce the need to specify many `Label` and `KeyTipText` values, except in scenarios where a customized value is necessary! diff --git a/Documentation/topics/bars/controls/popup-button.md b/Documentation/topics/bars/controls/popup-button.md index c870ba5a..9b93330d 100644 --- a/Documentation/topics/bars/controls/popup-button.md +++ b/Documentation/topics/bars/controls/popup-button.md @@ -24,6 +24,22 @@ Use the [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton) contr *BarPopupButton examples in several variant sizes (large, medium, and small)* +@if (avalonia) { +| Specification | Details | +|-----|-----| +| Base class | [BarPopupButtonBase](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase), which inherits native `Menu`. | +| Has key | Yes, via the [Key](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.Key) property. | +| Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.Label) property. Auto-generated from the `Key` value if not specified. | +| Has image | Yes, via the [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.SmallImageSource), [MediumImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.MediumImageSource), and [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.LargeImageSource) properties. | +| Has popup | Yes. | +| Is checkable | No. | +| Variant sizes | `Small` (image only), `Medium` (image and label), `Large` (tall size, image and multi-line label). | +| Command support | Yes, via the [PopupOpeningCommand](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.PopupOpeningCommand) property. | +| Key tip support | Yes, via the [KeyTipText](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.KeyTipText) property. Auto-generated from the `Label` value if not specified. | +| [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.CanCloneToRibbonQuickAccessToolBar) property. | +| [MVVM Library](../mvvm-support.md) VM | [BarPopupButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarPopupButtonViewModel) class. | +} +@if (wpf) { | Specification | Details | |-----|-----| | Base class | [BarPopupButtonBase](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase), which inherits native `Menu`. | @@ -38,7 +54,30 @@ Use the [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton) contr | [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.CanCloneToRibbonQuickAccessToolBar) property. | | UI density support | Yes, via the [UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.UserInterfaceDensity) property. | | [MVVM Library](../mvvm-support.md) VM | [BarPopupButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarPopupButtonViewModel) class. | +} +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -58,15 +97,39 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ### Menu Contexts Use the [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) control to implement a popup button concept within a menu context. +@if (avalonia) { +![Screenshot](../images/popup-button-menu.png) + +*A BarMenuItem with a child menu* +} +@if (wpf) { ![Screenshot](../images/menu-popup-large.png) *A BarMenuItem with large size showing a popup menu* +} +@if (avalonia) { +| Specification | Details | +|-----|-----| +| Base class | Native `MenuItem`. | +| Has key | Yes, via the [Key](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Key) property. | +| Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Label) property. Auto-generated from the `Key` value if not specified. | +| Has image | Yes, via the [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallImageSource) and [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeImageSource) properties. | +| Has popup | Yes. | +| Is checkable | No. | +| Variant sizes | None, but has a [UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.UseLargeSize) property that triggers a large height and displays an extended [Description](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Description). | +| Command support | Yes, via the [PopupOpeningCommand](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.PopupOpeningCommand) property. | +| Key tip support | Yes, via the [KeyTipText](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.KeyTipText) property. Auto-generated from the `Label` value if not specified. | +| [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.CanCloneToRibbonQuickAccessToolBar) property. | +| [MVVM Library](../mvvm-support.md) VM | [BarPopupButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarPopupButtonViewModel) class. | +} +@if (wpf) { | Specification | Details | |-----|-----| | Base class | Native `MenuItem`. | @@ -81,7 +144,28 @@ Use the [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) control to | [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.CanCloneToRibbonQuickAccessToolBar) property. | | UI density support | None. | | [MVVM Library](../mvvm-support.md) VM | [BarPopupButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarPopupButtonViewModel) class. | +} + +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -99,6 +183,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ## Appearance @@ -112,11 +197,20 @@ The `Label` can be auto-generated based on the control's `Key` property. For in The [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton).[Label](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.Label) is rendered on the button when it is in a `Medium` or `Large` variant size. When using a `Large` variant size button, the label will wrap words to two lines to minimize overall width. In cases where a run of label text should not be broken up into two lines, use a non-breaking space character (ASCII code 160) in place of any whitespace, like this: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} The [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).[Label](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Label) is rendered on the menu item as its primary content. @@ -124,7 +218,7 @@ The [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).[Label](xref:@A The controls can display images that help identify their function. -All [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton) instances should set a [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.SmallImageSource) at a minimum, which is generally used for `Small` and `Medium` variants, as well as in the [Ribbon Quick Access Toolbar](../ribbon-features/quick-access-toolbar.md) and if the control overflows to a menu. If the button supports a `Large` variant size, it should also define a [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.LargeImageSource). When the button has a `Spacious` UI density, it will try to use [MediumImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.MediumImageSource). +All [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton) instances should set a [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.SmallImageSource) at a minimum, which is generally used for `Small` and `Medium` variants, as well as in the [Ribbon Quick Access Toolbar](../ribbon-features/quick-access-toolbar.md) and if the control overflows to a menu. If the button supports a `Large` variant size, it should also define a [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.LargeImageSource). @if (avalonia) { When the button is located on a ribbon with `Simplified` layout mode, }@if (wpf) { When the button has a `Spacious` UI density,} it will try to use [MediumImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.MediumImageSource). > [!TIP] > See the [Control Basics](control-basics.md) topic for more detail on the fallback logic for button images. @@ -149,9 +243,11 @@ While [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) doesn't suppo See the [Resizing and Variants](../ribbon-features/resizing.md) topic for more information on ribbon's variant sizing features. +@if (wpf) { ### User Interface Density (BarPopupButton only) The [UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.UserInterfaceDensity) property can alter the appearance of the button, such as its size, padding, and image used. This property is not generally set on the button instance itself, and is instead meant to be set on the root bar control to inherit down, such as with the [Ribbon.UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.Ribbon.UserInterfaceDensity) property. +} ## Key Tips @@ -165,11 +261,21 @@ See the [Key Tips](../ribbon-features/key-tips.md) topic for more information on ## Commands and Events +@if (avalonia) { +The `ICommand` in the [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton).[Command](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.Command) property is never executed or used. +} +@if (wpf) { The `ICommand` in the [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton).[Command](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.Command) property is never executed or used other than to possibly initialize a label. +} The `ICommand` in the [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton).[PopupOpeningCommand](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.PopupOpeningCommand) property, and similarly the [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).[PopupOpeningCommand](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.PopupOpeningCommand), is executed prior to the popup or sub-menu opening. This command can be handled in a view model, allowing for a MVVM way to update the items on the popup prior to display. +@if (avalonia) { +[BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton).[Opening](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.Opening) and `MenuBase.Opened` events are raised when the popup is opened. The former event allows you to customize the popup menu prior to display. +} +@if (wpf) { [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton).[PopupOpening](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.PopupOpening) and [PopupOpened](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.PopupOpened) events are raised when the popup is opened. The former event allows you to customize the popup menu prior to display. +} The `PopupOpeningCommand`'s can-execute result determines the enabled state of the control. @@ -181,7 +287,7 @@ The controls support screen tips, which are formatted tool tips. The control's `Title` is used as the default screen tip header, falling back to `Label` if no `Title` is available. The [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton).[ScreenTipHeader](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.ScreenTipHeader) and [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).[ScreenTipHeader](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.ScreenTipHeader) properties can override the default screen tip header value if desired. -If the control's `ToolTip` property is set to a value that doesn't derive from a native `ToolTip` control, such as a string, the value will be used in the screen tip's content area, with the screen tip header becoming bold. The screen tip's content area is where extended descriptions are displayed. +If the control's @if (avalonia) { `ToolTip.Tip` }@if (wpf) { `ToolTip` } property is set to a value that doesn't derive from a native `ToolTip` control, such as a string, the value will be used in the screen tip's content area, with the screen tip header becoming bold. The screen tip's content area is where extended descriptions are displayed. If the optional [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton).[ScreenTipFooter](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.ScreenTipFooter) and [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem).[ScreenTipFooter](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.ScreenTipFooter) properties are specified, they will appear in a footer area of the screen tip. diff --git a/Documentation/topics/bars/controls/separator.md b/Documentation/topics/bars/controls/separator.md index 74c6c91d..91389f01 100644 --- a/Documentation/topics/bars/controls/separator.md +++ b/Documentation/topics/bars/controls/separator.md @@ -35,6 +35,22 @@ Use the [BarSeparator](xref:@ActiproUIRoot.Controls.Bars.BarSeparator) control t *A separator in a toolbar* +@if (avalonia) { +| Specification | Details | +|-----|-----| +| Base class | Native `Separator`. | +| Has key | No. | +| Has label | No. | +| Has image | No. | +| Has popup | No. | +| Is checkable | No. | +| Variant sizes | None. | +| Command support | None. | +| Key tip support | None. | +| [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | None. | +| [MVVM Library](../mvvm-support.md) VM | [BarSeparatorViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarSeparatorViewModel) class. | +} +@if (wpf) { | Specification | Details | |-----|-----| | Base class | Native `Separator`. | @@ -49,7 +65,24 @@ Use the [BarSeparator](xref:@ActiproUIRoot.Controls.Bars.BarSeparator) control t | [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | None. | | UI density support | None. | | [MVVM Library](../mvvm-support.md) VM | [BarSeparatorViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarSeparatorViewModel) class. | +} +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -63,6 +96,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ### Menu Contexts @@ -72,6 +106,22 @@ Use the [BarMenuSeparator](xref:@ActiproUIRoot.Controls.Bars.BarMenuSeparator) c *A separator in a menu* +@if (avalonia) { +| Specification | Details | +|-----|-----| +| Base class | Native `Separator`. | +| Has key | No. | +| Has label | No. | +| Has image | No. | +| Has popup | No. | +| Is checkable | No. | +| Variant sizes | None. | +| Command support | None. | +| Key tip support | None. | +| [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | None. | +| [MVVM Library](../mvvm-support.md) VM | [BarSeparatorViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarSeparatorViewModel) class. | +} +@if (wpf) { | Specification | Details | |-----|-----| | Base class | Native `Separator`. | @@ -86,7 +136,24 @@ Use the [BarMenuSeparator](xref:@ActiproUIRoot.Controls.Bars.BarMenuSeparator) c | [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | None. | | UI density support | None. | | [MVVM Library](../mvvm-support.md) VM | [BarSeparatorViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarSeparatorViewModel) class. | +} +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -100,6 +167,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} #### Separators Surrounding Menu Galleries diff --git a/Documentation/topics/bars/controls/split-button.md b/Documentation/topics/bars/controls/split-button.md index 0ebc3cc4..458f06ae 100644 --- a/Documentation/topics/bars/controls/split-button.md +++ b/Documentation/topics/bars/controls/split-button.md @@ -26,6 +26,22 @@ If the button should be checkable, use the [BarSplitToggleButton](xref:@ActiproU *BarSplitButton examples in several variant sizes (large, medium, and small)* +@if (avalonia) { +| Specification | Details | +|-----|-----| +| Base class | [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton), which indirectly inherits native `Menu`. | +| Has key | Yes, via the [Key](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.Key) property. | +| Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.Label) property. Auto-generated from the `Key` value if not specified. | +| Has image | Yes, via the [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.SmallImageSource), [MediumImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.MediumImageSource), and [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.LargeImageSource) properties. | +| Has popup | Yes. | +| Is checkable | Yes, but only when using [BarSplitToggleButton](xref:@ActiproUIRoot.Controls.Bars.BarSplitToggleButton). | +| Variant sizes | `Small` (image only), `Medium` (image and label), `Large` (tall size, image and multi-line label). | +| Command support | Yes, via the [Command](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.Command) property (related to the button portion) and the [PopupOpeningCommand](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.PopupOpeningCommand) property (related to the popup portion). | +| Key tip support | Yes, via the [KeyTipText](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.KeyTipText) property. Auto-generated from the `Label` value if not specified. | +| [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.CanCloneToRibbonQuickAccessToolBar) property. | +| [MVVM Library](../mvvm-support.md) VM | [BarSplitButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarSplitButtonViewModel) class for regular buttons, [BarSplitToggleButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarSplitToggleButtonViewModel) class for toggle buttons. | +} +@if (wpf) { | Specification | Details | |-----|-----| | Base class | [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton), which indirectly inherits native `Menu`. | @@ -40,7 +56,31 @@ If the button should be checkable, use the [BarSplitToggleButton](xref:@ActiproU | [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.CanCloneToRibbonQuickAccessToolBar) property. | | UI density support | Yes, via the [UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.UserInterfaceDensity) property. | | [MVVM Library](../mvvm-support.md) VM | [BarSplitButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarSplitButtonViewModel) class for regular buttons, [BarSplitToggleButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarSplitToggleButtonViewModel) class for toggle buttons. | +} +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -49,7 +89,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" + Command="{Binding InsertLastShapeCommand}"> ``` +} ### Menu Contexts @@ -72,6 +113,22 @@ The [BarSplitMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarSplitMenuItem) class *A BarSplitMenuItem example* +@if (avalonia) { +| Specification | Details | +|-----|-----| +| Base class | [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem), which indirectly inherits native `MenuItem`. | +| Has key | Yes, via the [Key](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Key) property. | +| Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Label) property. Auto-generated from the `Key` value if not specified. | +| Has image | Yes, via the [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallImageSource) and [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeImageSource) properties. | +| Has popup | Yes. | +| Is checkable | Yes, when the `ToggleType` property is set to `CheckBox` or `Radio`. | +| Variant sizes | None, but has a [UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.UseLargeSize) property that triggers a large height and displays an extended [Description](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Description). | +| Command support | Yes, via the `Command` property (related to the button portion) and the [PopupOpeningCommand](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.PopupOpeningCommand) property (related to the popup portion). | +| Key tip support | Yes, via the [KeyTipText](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.KeyTipText) property. Auto-generated from the `Label` value if not specified. | +| [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.CanCloneToRibbonQuickAccessToolBar) property. | +| [MVVM Library](../mvvm-support.md) VM | [BarSplitButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarSplitButtonViewModel) class for non-checkable menu items, [BarSplitToggleButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarSplitToggleButtonViewModel) class for checkable menu items. | +} +@if (wpf) { | Specification | Details | |-----|-----| | Base class | [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem), which indirectly inherits native `MenuItem`. | @@ -86,7 +143,29 @@ The [BarSplitMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarSplitMenuItem) class | [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.CanCloneToRibbonQuickAccessToolBar) property. | | UI density support | None. | | [MVVM Library](../mvvm-support.md) VM | [BarSplitButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarSplitButtonViewModel) class for non-checkable menu items, [BarSplitToggleButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarSplitToggleButtonViewModel) class for checkable menu items. | +} +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + Command="{Binding InsertLastShapeCommand}"> + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -105,6 +184,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ## Appearance @@ -118,11 +198,20 @@ The `Label` can be auto-generated based on the control's `Key` property. For in The [BarSplitButton](xref:@ActiproUIRoot.Controls.Bars.BarSplitButton).[Label](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.Label) is rendered on the button when it is in a `Medium` or `Large` variant size. When using a `Large` variant size button, the label will wrap words to two lines to minimize overall width. In cases where a run of label text should not be broken up into two lines, use a non-breaking space character (ASCII code 160) in place of any whitespace, like this: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} The [BarSplitMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarSplitMenuItem).[Label](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.Label) is rendered on the menu item as its primary content. @@ -130,7 +219,7 @@ The [BarSplitMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarSplitMenuItem).[Labe The controls can display images that help identify their function. -All [BarSplitButton](xref:@ActiproUIRoot.Controls.Bars.BarSplitButton) instances should set a [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.SmallImageSource) at a minimum, which is generally used for `Small` and `Medium` variants, as well as in the [Ribbon Quick Access Toolbar](../ribbon-features/quick-access-toolbar.md) and if the control overflows to a menu. If the button supports a `Large` variant size, it should also define a [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.LargeImageSource). When the button has a `Spacious` UI density, it will try to use [MediumImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.MediumImageSource). +All [BarSplitButton](xref:@ActiproUIRoot.Controls.Bars.BarSplitButton) instances should set a [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.SmallImageSource) at a minimum, which is generally used for `Small` and `Medium` variants, as well as in the [Ribbon Quick Access Toolbar](../ribbon-features/quick-access-toolbar.md) and if the control overflows to a menu. If the button supports a `Large` variant size, it should also define a [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.LargeImageSource). @if (avalonia) { When the button is located on a ribbon with `Simplified` layout mode, }@if (wpf) { When the button has a `Spacious` UI density,} it will try to use [MediumImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.MediumImageSource). > [!TIP] > See the [Control Basics](control-basics.md) topic for more detail on the fallback logic for button images. @@ -156,9 +245,11 @@ While [BarSplitMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarSplitMenuItem) doe See the [Resizing and Variants](../ribbon-features/resizing.md) topic for more information on ribbon's variant sizing features. +@if (wpf) { ### User Interface Density (BarSplitButton only) The [UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.UserInterfaceDensity) property can alter the appearance of the button, such as its size, padding, and image used. This property is not generally set on the button instance itself, and is instead meant to be set on the root bar control to inherit down, such as with the [Ribbon.UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.Ribbon.UserInterfaceDensity) property. +} ### Checked State (BarToggleSplitButton and BarSplitMenuItem only) @@ -188,13 +279,19 @@ See the [Using Commands](using-commands.md) topic for more information on comman ## Input Gesture Text -The control can have input gesture text associated with it that describes a related keyboard shortcut, -and is displayed in the screen tip for the control or in the menu item itself. +The control can have input gesture text associated with it that describes a related keyboard shortcut, and is displayed in the screen tip for the control or in the menu item itself. + +@if (avalonia) { +Input gesture text can be specified in the [BarSplitButton](xref:@ActiproUIRoot.Controls.Bars.BarSplitButton).[InputGesture](xref:@ActiproUIRoot.Controls.Bars.BarButton.InputGesture) and [BarSplitMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarSplitMenuItem).`InputGesture` properties. +Input gesture text may be hidden altogether in UI by setting the [BarSplitButton](xref:@ActiproUIRoot.Controls.Bars.BarSplitButton).[IsInputGestureTextVisible](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.IsInputGestureTextVisible) and [BarSplitMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarSplitMenuItem).[IsInputGestureTextVisible](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.IsInputGestureTextVisible) properties to `false`. +} +@if (wpf) { This input gesture text is automatically derived from commands that inherit `RoutedCommand` and have a `KeyGesture` set. Or input gesture text can be specified in the [BarSplitButton](xref:@ActiproUIRoot.Controls.Bars.BarSplitButton).[InputGestureText](xref:@ActiproUIRoot.Controls.Bars.BarSplitButton.InputGestureText) and [BarSplitMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarSplitMenuItem).`InputGestureText` properties. Input gesture text may be hidden altogether in UI by setting the [BarSplitButton](xref:@ActiproUIRoot.Controls.Bars.BarSplitButton).[IsInputGestureTextVisible](xref:@ActiproUIRoot.Controls.Bars.BarSplitButton.IsInputGestureTextVisible) and [BarSplitMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarSplitMenuItem).[IsInputGestureTextVisible](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.IsInputGestureTextVisible) properties to `false`. +} ## Screen Tips @@ -202,7 +299,7 @@ The controls support screen tips, which are formatted tool tips. The control's `Title` is used as the default screen tip header, falling back to `Label` if no `Title` is available. The [BarSplitButton](xref:@ActiproUIRoot.Controls.Bars.BarSplitButton).[ScreenTipHeader](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.ScreenTipHeader) and [BarSplitMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarSplitMenuItem).[ScreenTipHeader](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.ScreenTipHeader) properties can override the default screen tip header value if desired. -If the control's `ToolTip` property is set to a value that doesn't derive from a native `ToolTip` control, such as a string, the value will be used in the screen tip's content area, with the screen tip header becoming bold. The screen tip's content area is where extended descriptions are displayed. +If the control's @if (avalonia) { `ToolTip.Tip` }@if (wpf) { `ToolTip` } property is set to a value that doesn't derive from a native `ToolTip` control, such as a string, the value will be used in the screen tip's content area, with the screen tip header becoming bold. The screen tip's content area is where extended descriptions are displayed. If the optional [BarSplitButton](xref:@ActiproUIRoot.Controls.Bars.BarSplitButton).[ScreenTipFooter](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.ScreenTipFooter) and [BarSplitMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarSplitMenuItem).[ScreenTipFooter](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.ScreenTipFooter) properties are specified, they will appear in a footer area of the screen tip. diff --git a/Documentation/topics/bars/controls/textbox.md b/Documentation/topics/bars/controls/textbox.md index 60ca0c9a..e9a4d873 100644 --- a/Documentation/topics/bars/controls/textbox.md +++ b/Documentation/topics/bars/controls/textbox.md @@ -22,6 +22,22 @@ Use the [BarTextBox](xref:@ActiproUIRoot.Controls.Bars.BarTextBox) control to im *A BarTextBox example* +@if (avalonia) { +| Specification | Details | +|-----|-----| +| Base class | Native `TextBox`. | +| Has key | Yes, via the [Key](xref:@ActiproUIRoot.Controls.Bars.BarTextBox.Key) property. | +| Has label | Yes, via the [Label](xref:@ActiproUIRoot.Controls.Bars.BarTextBox.Label) property. Auto-generated from the `Key` value if not specified. | +| Has image | Yes, via the [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarTextBox.SmallImageSource) property. | +| Has popup | No. | +| Is checkable | No. | +| Variant sizes | None. | +| Command support | Yes, via the [Command](xref:@ActiproUIRoot.Controls.Bars.BarTextBox.Command) property. | +| Key tip support | Yes, via the [KeyTipText](xref:@ActiproUIRoot.Controls.Bars.BarTextBox.KeyTipText) property. Auto-generated from the `Label` value if not specified. | +| [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarTextBox.CanCloneToRibbonQuickAccessToolBar) property. | +| [MVVM Library](../mvvm-support.md) VM | [BarTextBoxViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarTextBoxViewModel) class. | +} +@if (wpf) { | Specification | Details | |-----|-----| | Base class | Native `TextBox`. | @@ -36,7 +52,24 @@ Use the [BarTextBox](xref:@ActiproUIRoot.Controls.Bars.BarTextBox) control to im | [Ribbon QAT](../ribbon-features/quick-access-toolbar.md) support | Yes, via the [CanCloneToRibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.BarTextBox.CanCloneToRibbonQuickAccessToolBar) property. | | UI density support | None. | | [MVVM Library](../mvvm-support.md) VM | [BarTextBoxViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarTextBoxViewModel) class. | +} +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -50,17 +83,33 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ### Menu Contexts Use the [BarTextBox](xref:@ActiproUIRoot.Controls.Bars.BarTextBox) control described above to implement a textbox concept within a menu context. -Since [BarTextBox](xref:@ActiproUIRoot.Controls.Bars.BarTextBox) is not flagged as a menu control via the [BarControlService](xref:@ActiproUIRoot.Controls.Bars.BarControlService).[IsMenuControlProperty](xref:@ActiproUIRoot.Controls.Bars.BarControlService.IsMenuControlProperty) attached property, it will be wrapped by a [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.BarMenuControlWrapper) instance when parented by a Bars menu control. [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.BarMenuControlWrapper) is a special control that can wrap interactive controls like [BarTextBox](xref:@ActiproUIRoot.Controls.Bars.BarTextBox) that are not normally intended for use in a menu. It displays the wrapped control's label externally from the wrapped control itself and applies horizontal margins to align everything with surrounding menu items properly. +Since [BarTextBox](xref:@ActiproUIRoot.Controls.Bars.BarTextBox) is not flagged as a menu control via the [BarControlService](xref:@ActiproUIRoot.Controls.Bars.BarControlService).[IsMenuControlProperty](xref:@ActiproUIRoot.Controls.Bars.BarControlService.IsMenuControlProperty) attached property, it will be wrapped by a @if (avalonia) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuControlWrapper) }@if (wpf) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.BarMenuControlWrapper) } instance when parented by a Bars menu control. @if (avalonia) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuControlWrapper) }@if (wpf) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.BarMenuControlWrapper) } is a special control that can wrap interactive controls like [BarTextBox](xref:@ActiproUIRoot.Controls.Bars.BarTextBox) that are not normally intended for use in a menu. It displays the wrapped control's label externally from the wrapped control itself and applies horizontal margins to align everything with surrounding menu items properly. ![Screenshot](../images/textbox-menu.png) *A BarTextBox when in a menu, wrapped by BarMenuControlWrapper* +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -73,9 +122,10 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} > [!NOTE] -> See the [Using Custom Controls](using-custom-controls.md) topic for more information on [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.BarMenuControlWrapper). +> See the [Using Custom Controls](using-custom-controls.md) topic for more information on @if (avalonia) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuControlWrapper) }@if (wpf) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.BarMenuControlWrapper) }. ## Appearance @@ -87,7 +137,7 @@ The `Text` property gets or sets the text that is displayed within the textbox. ### Label -The control has a string [Label](xref:@ActiproUIRoot.Controls.Bars.BarTextBox.Label) that can be set, which is visible in UI. The label is not rendered by the control itself, but can show externally (such as when in a [RibbonControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonControlGroup), or when [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.BarMenuControlWrapper) wraps [BarTextBox](xref:@ActiproUIRoot.Controls.Bars.BarTextBox) in a menu), in screen tips, or in customization UI. +The control has a string [Label](xref:@ActiproUIRoot.Controls.Bars.BarTextBox.Label) that can be set, which is visible in UI. The label is not rendered by the control itself, but can show externally (such as when in a [RibbonControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonControlGroup), or when @if (avalonia) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuControlWrapper) }@if (wpf) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.BarMenuControlWrapper) } wraps [BarTextBox](xref:@ActiproUIRoot.Controls.Bars.BarTextBox) in a menu), in screen tips, or in customization UI. ![Screenshot](../images/textbox-medium.png) @@ -97,7 +147,7 @@ The `Label` can be auto-generated based on the control's `Key` property. For in ### Images -The control can display an image via [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarTextBox.SmallImageSource) that helps identify its function. The image is not rendered by the control itself, but can show externally (such as when in a [RibbonControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonControlGroup), or when [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.BarMenuControlWrapper) wraps [BarTextBox](xref:@ActiproUIRoot.Controls.Bars.BarTextBox) in a menu), or in customization UI. +The control can display an image via [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarTextBox.SmallImageSource) that helps identify its function. The image is not rendered by the control itself, but can show externally (such as when in a [RibbonControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonControlGroup), or when @if (avalonia) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuControlWrapper) }@if (wpf) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.BarMenuControlWrapper) } wraps [BarTextBox](xref:@ActiproUIRoot.Controls.Bars.BarTextBox) in a menu), or in customization UI. ### Title @@ -145,7 +195,7 @@ The controls support screen tips, which are formatted tool tips. The control's `Title` is used as the default screen tip header, falling back to `Label` if no `Title` is available. The [ScreenTipHeader](xref:@ActiproUIRoot.Controls.Bars.BarTextBox.ScreenTipHeader) property can override the default screen tip header value if desired. -If the control's `ToolTip` property is set to a value that doesn't derive from a native `ToolTip` control, such as a string, the value will be used in the screen tip's content area, with the screen tip header becoming bold. The screen tip's content area is where extended descriptions are displayed. +If the control's @if (avalonia) { `ToolTip.Tip` }@if (wpf) { `ToolTip` } property is set to a value that doesn't derive from a native `ToolTip` control, such as a string, the value will be used in the screen tip's content area, with the screen tip header becoming bold. The screen tip's content area is where extended descriptions are displayed. If the optional [ScreenTipFooter](xref:@ActiproUIRoot.Controls.Bars.BarTextBox.ScreenTipFooter) property is specified, it will appear in a footer area of the screen tip. diff --git a/Documentation/topics/bars/controls/using-commands.md b/Documentation/topics/bars/controls/using-commands.md index 09b7fa12..fc3c70b9 100644 --- a/Documentation/topics/bars/controls/using-commands.md +++ b/Documentation/topics/bars/controls/using-commands.md @@ -5,13 +5,18 @@ order: 200 --- # Using Commands -All interactive controls in this product are designed to work well with MVVM patterns and the WPF command model. +All interactive controls in this product are designed to work well with MVVM patterns and the @@PlatformTitle command model. Controls will execute their command when a primary action occurs on the control, and use the `ICommand.CanExecute` result to determine if the control is enabled. Commands can be used to support live preview for gallery items as well. ## Control Command Support -Many controls implement `ICommandSource`, meaning that they have `Command`, `CommandParameter`, and `CommandTarget` properties. The `ICommand` that is assigned to a control can be any command, including those defined in the WPF framework in the `System.Windows.Input` namespace, those created by Actipro in the [ActiproSoftware.Windows.Input](xref:@ActiproUIRoot.Input) namespace, or any other third-party commands. +@if (avalonia) { +Many controls implement `ICommandSource`, meaning that they have `Command` and `CommandParameter` properties. The `ICommand` that is assigned to a control can be any command, including those created by Actipro in the [ActiproSoftware.UI.Avalonia.Input](xref:@ActiproUIRoot.Input) namespace, custom commands, or any other third-party commands. +} +@if (wpf) { +Many controls implement `ICommandSource`, meaning that they have `Command`, `CommandParameter`, and `CommandTarget` properties. The `ICommand` that is assigned to a control can be any command, including those defined in the WPF framework in the `System.Windows.Input` namespace, those created by Actipro in the [ActiproSoftware.Windows.Input](xref:@ActiproUIRoot.Input) namespace, custom commands, or any other third-party commands. +} ### Summary Table @@ -39,7 +44,7 @@ The `ICommand` interface provides the foundation of any command and includes sup Controls will execute the command when their primary action occurs, such as a button being clicked. Controls will also use the `ICommand.CanExecute` result to determine if the control should be enabled. -Actipro provides couple useful implementations of the `ICommand` interface that are described below. +Actipro provides useful implementations of the `ICommand` interface that are described below. ### IPreviewableCommand (Live Preview Support) @@ -54,13 +59,14 @@ These are the important methods on the [IPreviewableCommand](xref:@ActiproUIRoot The caller of these methods should always cancel a previous preview prior to starting a new preview. -Actipro provides couple useful implementations of the [IPreviewableCommand](xref:@ActiproUIRoot.Input.IPreviewableCommand) interface that are described below. +Actipro provides useful implementations of the [IPreviewableCommand](xref:@ActiproUIRoot.Input.IPreviewableCommand) interface that are described below. +@if (wpf) { ## Framework Command Types The WPF framework has a couple built-in types that implement `ICommand`. -## RoutedCommand +### RoutedCommand `RoutedCommand` defines a command that is routed through the element tree. The `Execute` and `CanExecute` methods on a `RoutedCommand` do not contain the application logic for the command as is the case with a typical `ICommand`, but rather, these methods raise events that traverse the element tree looking for an object with a `CommandBinding`. The event handlers attached to the `CommandBinding` contain the command logic. @@ -69,15 +75,21 @@ Screen tips and menu items are able to locate any `KeyBinding` that is on the `R > [!IMPORTANT] > A `RoutedCommand` is dependent upon the visual tree for handling commands. When working with [Ribbon](../ribbon-features/index.md), the [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage) and [RibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBar) controls are not always visual children of the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) control. This means the ideal location to define a `CommandBinding` for a `RoutedCommand` is on the `Window` that contains the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) control. -## RoutedUICommand +### RoutedUICommand `RoutedUICommand` inherits `RoutedCommand` and has the same general design, but with the additional benefit that it contains a `Text` property too. +} ## Delegate Command Types +@if (avalonia) { +Delegate commands are passed a delegate for execute, can-execute, etc. logic. +} +@if (wpf) { Delegate commands are often preferred to routed commands in more complex apps, and those that use MVVM. Delegate commands are passed a delegate for execute, can-execute, etc. logic. +} -Actipro includes a couple implementations of delegate commands in the Shared Library. +Actipro includes implementations of delegate commands in the Shared Library. ### DelegateCommand\ @@ -118,7 +130,7 @@ var setTextStyleCommand = new PreviewableDelegateCommand + + + + + ... + + + ... + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" xmlns:editors="http://schemas.actiprosoftware.com/winfx/xaml/editors" @@ -61,6 +91,7 @@ xmlns:editors="http://schemas.actiprosoftware.com/winfx/xaml/editors" ``` +} ### Simplified Ribbon @@ -74,6 +105,24 @@ A custom control can be cloned to the [Quick Access Toolbar](../ribbon-features/ A custom control hosted within a toolbar will also use a small control height. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" xmlns:editors="http://schemas.actiprosoftware.com/winfx/xaml/editors" @@ -92,15 +141,35 @@ xmlns:editors="http://schemas.actiprosoftware.com/winfx/xaml/editors" ... ``` +} ### Menu -Custom controls don't always work well in menu contexts, but a special [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.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. +Custom controls don't always work well in menu contexts, but a special @if (avalonia) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuControlWrapper) }@if (wpf) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.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](xref:@ActiproUIRoot.Controls.Bars.BarMenuControlWrapper) instance. A control can be flagged as a menu control by setting the [BarControlService](xref:@ActiproUIRoot.Controls.Bars.BarControlService).[IsMenuControlProperty](xref:@ActiproUIRoot.Controls.Bars.BarControlService.IsMenuControlProperty) attached property set to `true`. +Bars menu controls will automatically wrap child controls that aren't flagged as menu controls with a @if (avalonia) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuControlWrapper) }@if (wpf) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.BarMenuControlWrapper) } instance. A control can be flagged as a menu control by setting the [BarControlService](xref:@ActiproUIRoot.Controls.Bars.BarControlService).[IsMenuControlProperty](xref:@ActiproUIRoot.Controls.Bars.BarControlService.IsMenuControlProperty) attached property set to `true`. -The [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.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](xref:@ActiproUIRoot.Controls.Bars.BarMenuControlWrapper).`Header` property for proper display, which happens automatically if the custom control is within a Bars menu control. +The @if (avalonia) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuControlWrapper) }@if (wpf) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.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 @if (avalonia) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuControlWrapper) }@if (wpf) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.BarMenuControlWrapper) }.`Header` property for proper display, which happens automatically if the custom control is within a Bars menu control. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" xmlns:editors="http://schemas.actiprosoftware.com/winfx/xaml/editors" @@ -120,13 +189,29 @@ xmlns:editors="http://schemas.actiprosoftware.com/winfx/xaml/editors" ... ``` +} -When a label and/or small image are applied to a custom control with the attached [LabelProperty](xref:@ActiproUIRoot.Controls.Bars.BarControlService.LabelProperty) and [SmallImageSourceProperty](xref:@ActiproUIRoot.Controls.Bars.BarControlService.SmallImageSourceProperty) properties, they will be displayed in the [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.BarMenuControlWrapper) alongside the custom control itself. The small image will align in the icon column with other menu items. +When a label and/or small image are applied to a custom control with the attached [LabelProperty](xref:@ActiproUIRoot.Controls.Bars.BarControlService.LabelProperty) and [SmallImageSourceProperty](xref:@ActiproUIRoot.Controls.Bars.BarControlService.SmallImageSourceProperty) properties, they will be displayed in the @if (avalonia) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarMenuControlWrapper) }@if (wpf) { [BarMenuControlWrapper](xref:@ActiproUIRoot.Controls.Bars.BarMenuControlWrapper) } alongside the custom control itself. The small image will align in the icon column with other menu items. ## Screen Tips The [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip) class inherits the native `ToolTip` control and therefore can be used anywhere a normal tooltip can, including on custom controls. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" xmlns:editors="http://schemas.actiprosoftware.com/winfx/xaml/editors" @@ -134,11 +219,12 @@ xmlns:editors="http://schemas.actiprosoftware.com/winfx/xaml/editors" - + ... ``` +} See the [Screen Tips](../ribbon-features/screen-tips.md) topic for more information on screen tips. diff --git a/Documentation/topics/bars/getting-started.md b/Documentation/topics/bars/getting-started.md index 8d8d998d..a35c74ea 100644 --- a/Documentation/topics/bars/getting-started.md +++ b/Documentation/topics/bars/getting-started.md @@ -13,7 +13,9 @@ Once you are ready to add Bars controls to your own application, first add refer [NuGet packages](../nuget.md) are available for all assemblies and are the recommended way to reference Actipro product assemblies. -For customers who prefer direct references to DLL files in their .NET Framework-based applications, the WPF Controls installer by default will install assemblies to the GAC, as well as into a *Program Files* folder whose path is listed in the product's Readme file. +@if (wpf) { +For customers who prefer direct references to DLL files in their .NET Framework-based applications, the WPF Controls installer will, by default, install assemblies to the GAC, as well as into a *Program Files* folder whose path is listed in the product's Readme file. +} ## Read the Documentation Topics @@ -39,6 +41,28 @@ The "Getting Started" series is probably the best place to go for quickly gettin This code shows the base XAML that you can use to define an empty [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) along with the recommended [RibbonWindow](ribbon-features/ribbon-window.md) and [RibbonContainerPanel](xref:@ActiproUIRoot.Controls.Bars.RibbonContainerPanel) controls: +@if (avalonia) { +```xaml + + + + + + + + + + + + + + +``` +} +@if (wpf) { ```xaml ``` +} ## Getting Started with Toolbar @@ -65,6 +90,25 @@ See the [Controls Overview](controls/index.md) for topics related to individual This code shows sample XAML that you can use to define a standalone toolbar with buttons: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + ... + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -81,6 +125,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ## Getting Started with Menu @@ -88,6 +133,24 @@ See the [Controls Overview](controls/index.md) for topics related to individual This code sample shows how to define a context menu for a `TextBox`: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + ... + + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -103,11 +166,13 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ``` +} ## Examine the Other QuickStarts We've spent a lot of time adding numerous QuickStarts for Bars that are in the sample project. Each QuickStart focuses on a specific feature area and provides some great code that you can look at to use in your own applications. +See the @if (avalonia) { [Samples](../samples.md) }@if (wpf) { [Sample Code and QuickStarts](../quick-starts.md) } topic for more information on accessing the sample project. ## Copy Code from the Sample Project diff --git a/Documentation/topics/bars/index.md b/Documentation/topics/bars/index.md index 8beef65d..13af3edf 100644 --- a/Documentation/topics/bars/index.md +++ b/Documentation/topics/bars/index.md @@ -17,8 +17,10 @@ Ribbon implements an Office-like user interface, complete with dynamic variant s See the [Ribbon Overview](ribbon-features/index.md) topic for additional information on working with a ribbon. +@if (wpf) { > [!NOTE] > The Bars product has no dependency on the older [Ribbon product](../ribbon/index.md). Bars includes a newer ribbon control implementation with a much-improved design and appearance, and with many of the latest features currently found in Office. The older Ribbon product [will be deprecated](../conversion/converting-to-v23-1.md) in the future in favor of the ribbon implementation in the Bars product, so it is recommended to implement new ribbons using the Bars product instead. +} ## Standalone Toolbar diff --git a/Documentation/topics/bars/localization.md b/Documentation/topics/bars/localization.md index f85681c9..4b998139 100644 --- a/Documentation/topics/bars/localization.md +++ b/Documentation/topics/bars/localization.md @@ -11,6 +11,19 @@ order: 405 Many controls utilize built-in strings as part of their presentation, and these strings are defined as resources which can be customized. For example, the [Ribbon Options Button](ribbon-features/options-button.md) displays several commands whose labels are based on string resources. +@if (avalonia) { +Bars string resources are customized using the `ActiproSoftware.Properties.Bars.SR` class and an enumeration of available resource names is available using `ActiproSoftware.Properties.Bars.SRName`. + +> [!NOTE] +> For those working with [MVVM](mvvm-support.md), additional string resources for that library can be customized using the `ActiproSoftware.Properties.Bars.Mvvm.SR` class and `ActiproSoftware.Properties.Bars.MVVM.SRName` enumeration. + +The following example demonstrates how one might customize the `UIRibbonMenuItemAlwaysShowRibbonText` string resource: + +```csharp +ActiproSoftware.Properties.Bars.SR.SetCustomString(ActiproSoftware.Properties.Bars.SRName.UIRibbonMenuItemAlwaysShowRibbonText, "Show Full Ribbon"); +``` +} +@if (wpf) { Bars string resources are customized using the `ActiproSoftware.Products.Bars.SR` class and an enumeration of available resource names is available using `ActiproSoftware.Products.Bars.SRName`. > [!NOTE] @@ -21,6 +34,7 @@ The following example demonstrates how one might customize the `UIRibbonMenuItem ```csharp ActiproSoftware.Products.Bars.SR.SetCustomString(ActiproSoftware.Products.Bars.SRName.UIRibbonMenuItemAlwaysShowRibbonText.ToString(), "Show Full Ribbon"); ``` +} See the [Customizing String Resources](../customizing-string-resources.md) topic for additional details. diff --git a/Documentation/topics/bars/menu-features/context-menus.md b/Documentation/topics/bars/menu-features/context-menus.md index b39b6b4b..b0fed9f5 100644 --- a/Documentation/topics/bars/menu-features/context-menus.md +++ b/Documentation/topics/bars/menu-features/context-menus.md @@ -21,6 +21,38 @@ A context menu is most often assigned to a control via its `ContextMenu` propert This sample code shows how to define a context menu for a `TextBox`: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + + + + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -50,6 +82,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ``` +} ## Stay Open on Menu Item Click @@ -71,6 +104,20 @@ By setting the [BarContextMenu](xref:@ActiproUIRoot.Controls.Bars.BarContextMenu The optional companion [MVVM Library](../mvvm-support.md) includes a [BarControlTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarControlTemplateSelector) class that is designed for use with the `ItemContainerTemplateSelector` property, when the control view models from the library are the items being bound via the control's `ItemsSource` property. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -82,6 +129,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ``` +} > [!TIP] > See the [MVVM Support](../mvvm-support.md) topic for more information on how to use the library's view models and view templates to create and manage your application's bars controls with MVVM techniques. diff --git a/Documentation/topics/bars/menu-features/menu-customization.md b/Documentation/topics/bars/menu-features/menu-customization.md index 801d3aab..d573cd30 100644 --- a/Documentation/topics/bars/menu-features/menu-customization.md +++ b/Documentation/topics/bars/menu-features/menu-customization.md @@ -36,7 +36,7 @@ The [RibbonQuickAccessToolBarCustomizeButton](xref:@ActiproUIRoot.Controls.Bars. Existing menu items can be modified/removed, and new menu items can be added. The following code shows an event handler for the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[MenuOpening](xref:@ActiproUIRoot.Controls.Bars.Ribbon.MenuOpening) event that updates the **Customize** menu to add an additional menu item (via a `CreateCustomMenuItem` method that you would create): ```csharp -private void OnRibbonMenuOpening(object sender, BarMenuEventArgs e) { +private void OnRibbonMenuOpening(object? sender, BarMenuEventArgs e) { // Test for the QAT customize menu if (e.Kind == BarMenuKind.RibbonQuickAccessToolBarCustomizeButtonMenu && e.Menu != null) { @@ -65,7 +65,7 @@ The [BarContextMenu](xref:@ActiproUIRoot.Controls.Bars.BarContextMenu).`Items` c Existing menu items can be modified/removed, and new menu items can be added. The following code shows an event handler for the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[MenuOpening](xref:@ActiproUIRoot.Controls.Bars.Ribbon.MenuOpening) event that updates the context menu to add an additional menu item (via a `CreateCustomMenuItem` method that you would create): ```csharp -private void OnRibbonMenuOpening(object sender, BarMenuEventArgs e) { +private void OnRibbonMenuOpening(object? sender, BarMenuEventArgs e) { // Test for a control context menu if (e.Kind == BarMenuKind.ControlContextMenu && e.Owner != null diff --git a/Documentation/topics/bars/mvvm-support.md b/Documentation/topics/bars/mvvm-support.md index 1743ae7f..71c7df95 100644 --- a/Documentation/topics/bars/mvvm-support.md +++ b/Documentation/topics/bars/mvvm-support.md @@ -17,39 +17,51 @@ Before getting into the contents of the MVVM library itself, let's examine the o ### Items Controls -Many Bars controls, especially those in the ribbon hierarchy, inherit the native `ItemsControl` class. This is key to the principle of supporting MVVM because it allows you to bind a collection of items (generally view models) to a control's `ItemsSource`. The control's item container generator will then examine each item and if it is not an allowed "container" element for the `ItemsControl`, it will ask for a "container" element to be generated. This is where `ItemContainerTemplateSelector` classes come into play. +Many Bars controls, especially those in the ribbon hierarchy, inherit the native `ItemsControl` class. This is key to the principle of supporting MVVM because it allows you to bind a collection of items (generally view models) to a control's `ItemsSource`. The control's item container generator will then examine each item and if it is not an allowed "container" element for the `ItemsControl`, it will ask for a "container" element to be generated. This is where @if (avalonia) { classes that implement [IItemContainerTemplateSelector](xref:ActiproSoftware.UI.Controls.Templates.IItemContainerTemplateSelector) }@if (wpf) { `ItemContainerTemplateSelector` classes } come into play. ### Item Container Template Selectors +@if (avalonia) { +Bars controls that derive from `ItemsControl` make heavy use of classes that implement [IItemContainerTemplateSelector](xref:ActiproSoftware.UI.Controls.Templates.IItemContainerTemplateSelector). This interface is designed so that an item, usually a view model, is passed into a [SelectTemplate](xref:ActiproSoftware.UI.Controls.Templates.IItemContainerTemplateSelector.SelectTemplate*) method along with a reference to the owner `ItemsControl`, and the method will return an `IDataTemplate` to be used for that item. + +The point of an [IItemContainerTemplateSelector](xref:ActiproSoftware.UI.Controls.Templates.IItemContainerTemplateSelector) is to generate a "container" element for an `ItemsControl`'s item. The [SelectTemplate](xref:ActiproSoftware.UI.Controls.Templates.IItemContainerTemplateSelector.SelectTemplate*) method returns an `IDataTemplate` that contains the element hierarchy to generate. The root element generated from that `IDataTemplate` will be used as the "container" for the item, and the item will be set as that "container" element's `DataContext`. +} +@if (wpf) { Bars controls that derive from `ItemsControl` make heavy use of `ItemContainerTemplateSelector` classes. This lesser-known class type works similarly to the `DataTemplateSelector` class, where an item (usually a view model) is passed into a `SelectTemplate` method, along with a control reference. The `DataTemplateSelector.SelectTemplate` method passes in the container control instance as the control reference, whereas the `ItemContainerTemplateSelector.SelectTemplate` method passes in the owner `ItemsControl` as the control reference. The point of an `ItemContainerTemplateSelector` is to generate a "container" element for an `ItemsControl`'s item. The `SelectTemplate` method returns an `ItemContainerTemplate` (a class that inherits `DataTemplate`) that contains the element hierarchy to generate. The root element generated from that `ItemContainerTemplate` will be used as the "container" for the item, and the item will be set as that "container" element's `DataContext`. +} ### Ribbon Example -As an example to the above process, let's consider the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) control. It inherits `Selector`, which in turn inherits native `ItemsControl`. It's set up to call into the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[ItemContainerTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Ribbon.ItemContainerTemplateSelector) that is currently assigned (if any) to try and generate a [RibbonTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonTabItem) "container" element for any item in its `ItemsSource` that doesn't derive from [RibbonTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonTabItem). +As an example to the above process, let's consider the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) control. It inherits @if (avalonia) { `SelectingItemsControl`, }@if (wpf) { `Selector`, } which in turn inherits native `ItemsControl`. It's set up to call into the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[ItemContainerTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Ribbon.ItemContainerTemplateSelector) that is currently assigned (if any) to try and generate a [RibbonTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonTabItem) "container" element for any item in its `ItemsSource` that doesn't derive from [RibbonTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonTabItem). Now say that a custom ribbon tab view model class (call it `RibbonTabViewModel`) is the type of item bound to the ribbon's `ItemsSource`, and there is one instance of the class for each tab in the ribbon. +@if (avalonia) { +It's the responsibility of the [SelectTemplate](xref:ActiproSoftware.UI.Controls.Templates.IItemContainerTemplateSelector.SelectTemplate*) method in the [IItemContainerTemplateSelector](xref:ActiproSoftware.UI.Controls.Templates.IItemContainerTemplateSelector) assigned to [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[ItemContainerTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Ribbon.ItemContainerTemplateSelector) to look at the `RibbonTabViewModel` and return an `IDataTemplate` that contains a [RibbonTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonTabItem) control at its root. The [RibbonTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonTabItem) XAML in the `IDataTemplate` should have bindings configured from the view model to the control. +} +@if (wpf) { It's the responsibility of the `SelectTemplate` method in the `ItemContainerTemplateSelector` assigned to [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[ItemContainerTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Ribbon.ItemContainerTemplateSelector) to look at the `RibbonTabViewModel` and return an `ItemContainerTemplate` that contains a [RibbonTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonTabItem) control at its root. The [RibbonTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonTabItem) XAML in the `ItemContainerTemplate` should have bindings configured from the view model to the control. +} > [!NOTE] -> Bars controls are set up to pass an `ItemContainerTemplateSelector` that is assigned down to any child controls. For instance, setting the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[ItemContainerTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Ribbon.ItemContainerTemplateSelector) property will pass that `ItemContainerTemplateSelector` down through tabs, groups, and even into popup menus. In this way, the same template selector instance can be reused throughout the control hierarchy. +> Bars controls are set up to pass an @if (avalonia) { [IItemContainerTemplateSelector](xref:ActiproSoftware.UI.Controls.Templates.IItemContainerTemplateSelector) }@if (wpf) { `ItemContainerTemplateSelector` } that is assigned down to any child controls. For instance, setting the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[ItemContainerTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Ribbon.ItemContainerTemplateSelector) property will pass that @if (avalonia) { [IItemContainerTemplateSelector](xref:ActiproSoftware.UI.Controls.Templates.IItemContainerTemplateSelector) }@if (wpf) { `ItemContainerTemplateSelector` } down through tabs, groups, and even into popup menus. In this way, the same template selector instance can be reused throughout the control hierarchy. With all of that in place, when a [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) sees a `RibbonTabViewModel` item in its `ItemsSource`, it will generate a [RibbonTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonTabItem) "container" that will have its `DataContext` set as the `RibbonTabViewModel` instance, and the tab will appear in the ribbon UI. -Properties on the `RibbonTabViewModel` may be modified, and as long as `INotifyPropertyChanged` is implemented on the view model class, the property changes will flow into the generated [RibbonTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonTabItem) via the bindings that were set up in the `ItemContainerTemplate`. +Properties on the `RibbonTabViewModel` may be modified, and as long as `INotifyPropertyChanged` is implemented on the view model class, the property changes will flow into the generated [RibbonTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonTabItem) via the bindings that were set up in the @if (avalonia) { `IDataTemplate`. }@if (wpf) { `ItemContainerTemplate`. } > [!TIP] -> View model classes can inherit the [ObservableObjectBase](xref:@ActiproUIRoot.ObservableObjectBase) class from the Shared Library to easily implement `INotifyPropertyChanged`. +> View model classes can inherit the @if (avalonia) { [ObservableObjectBase](xref:ActiproSoftware.ObservableObjectBase) class from the Core Library }@if (wpf) { [ObservableObjectBase](xref:@ActiproUIRoot.ObservableObjectBase) class from the Shared Library } to easily implement `INotifyPropertyChanged`. ### Gallery Item Content [RibbonGallery](xref:@ActiproUIRoot.Controls.Bars.RibbonGallery) and [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery) are graphically-rich list controls that support selection of anything from colors to text styles. Even when a ribbon hierarchy is constructed in pure XAML, gallery controls must still use MVVM for their items. -While galleries can use logic like above with an `ItemContainerTemplateSelector` to generate [BarGalleryItem](xref:@ActiproUIRoot.Controls.Bars.BarGalleryItem) "container" elements for their items, the actual items should always be some sort of view model. The visual content within a displayed gallery item is selected by a custom `DataTemplateSelector` instance set to the gallery's `ItemTemplateSelector` property. The `DataTemplateSelector.SelectTemplate` property is passed the view model item and returns a `DataTemplate` to use as the UI for the gallery item. +While galleries can use logic like above with an @if (avalonia) { [IItemContainerTemplateSelector](xref:ActiproSoftware.UI.Controls.Templates.IItemContainerTemplateSelector) }@if (wpf) { `ItemContainerTemplateSelector` } to generate [BarGalleryItem](xref:@ActiproUIRoot.Controls.Bars.BarGalleryItem) "container" elements for their items, the actual items should always be some sort of view model. The visual content within a displayed gallery item is selected by a custom @if (avalonia) { [IDataTemplateSelector](xref:ActiproSoftware.UI.Controls.Templates.IDataTemplateSelector) }@if (wpf) { `DataTemplateSelector` } instance set to the gallery's `ItemTemplateSelector` property. The @if (avalonia) { [IDataTemplateSelector](xref:ActiproSoftware.UI.Controls.Templates.IDataTemplateSelector).[SelectTemplate](xref:ActiproSoftware.UI.Controls.Templates.IDataTemplateSelector.SelectTemplate*) }@if (wpf) { `DataTemplateSelector.SelectTemplate` } method is passed the view model item and returns @if (avalonia) { an `IDataTemplate` }@if (wpf) { a `DataTemplate` } to use as the UI for the gallery item. -The `DataTemplate` may contain the complete UI for the gallery item, or it may include a custom element that knows how to measure and render itself in code-behind. The `DataContext` for the elements in the `DataTemplate` will be the gallery item view model, allowing for the view model's properties to be bound into any elements within the `DataTemplate`. +The @if (avalonia) { `IDataTemplate` }@if (wpf) { `DataTemplate` } may contain the complete UI for the gallery item, or it may include a custom element that knows how to measure and render itself in code-behind. The `DataContext` for the elements in the @if (avalonia) { `IDataTemplate` }@if (wpf) { `DataTemplate` } will be the gallery item view model, allowing for the view model's properties to be bound into any elements within the @if (avalonia) { `IDataTemplate`. }@if (wpf) { `DataTemplate`. } See the [Gallery](controls/gallery.md) topic for more information on galleries. @@ -57,6 +69,34 @@ See the [Gallery](controls/gallery.md) topic for more information on galleries. A [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage) control is effectively a tab control where each item generates a [RibbonBackstageTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageTabItem) "container" element if one isn't used directly as the item. Note that buttons and separators can also be used as backstage items. +@if (avalonia) { +If the [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage).`ItemsSource` is set to a collection of view models (`InfoRibbonBackstageTabViewModel`, `NewRibbonBackstageTabViewModel`, etc.), the [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage).`ContentTemplate` property can define the user interface for each tab's content. Two possible ways include: + +1. Assign a specialized `IDataTemplate` implementation to [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage).`ContentTemplate` that can examine a backstage tab view model and provide an appropriate `DataTemplate` instance to be used. For example, the [TypedDataTemplateSelector](xref:@ActiproUIRoot.Controls.Templates.TypedDataTemplateSelector) class can define implicit `DataTemplate` instances for each backstage tab with their `x:DataType` attributes set to the related view model type. + +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + + + + + + +``` + +2. Instead of setting the [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage).`ContentTemplate` property, add `DataTemplate` instances to the [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage).`DataTemplates` collection with each data template's `x:DataType` attribute set to the related view model type. +} +@if (wpf) { If the [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage).`ItemsSource` is set to a collection of view models, the [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage).`ContentTemplateSelector` can be set to a `DataTemplateSelector` that will return the `DataTemplate` for each tab's content. It's up to the `DataTemplateSelector.SelectTemplate` method to examine the backstage tab view model and return the appropriate `DataTemplate` for the related backstage tab's content. Alternatively, if distinct view model types (`InfoRibbonBackstageTabViewModel`, `NewRibbonBackstageTabViewModel`, etc.) are used as the backstage tab view models, the `Resources` of the [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage) control or the containing `Window` can contain implicit `DataTemplate` instances with their `DataType` attributes set to the related view model type, like this: @@ -72,19 +112,49 @@ Alternatively, if distinct view model types (`InfoRibbonBackstageTabViewModel`, ``` When using implicit `DataTemplate` resources, no `ContentTemplateSelector` is necessary. +} See the [Backstage](ribbon-features/backstage.md) topic for more information on backstage. ### Ribbon Footer Content +@if (avalonia) { +The [RibbonFooterControl](xref:@ActiproUIRoot.Controls.Bars.RibbonFooterControl) is a `ContentControl` and supports standard `IDataTemplate`-based content selection. +} +@if (wpf) { The [RibbonFooterControl](xref:@ActiproUIRoot.Controls.Bars.RibbonFooterControl) is a `ContentControl` and supports both `DataTemplateSelector` and implicit `DataTemplate`-based content selection. +} See the [Footer](ribbon-features/footer.md) topic for more information on ribbon footers. ### Container Element Summary -This table summarizes most of the `ItemsControl`-based controls in Bars and which "container" elements they expect to be generated from an `ItemContainerTemplateSelector`: +This table summarizes most of the `ItemsControl`-based controls in Bars and which "container" elements they expect to be generated from an @if (avalonia) { [IItemContainerTemplateSelector](xref:ActiproSoftware.UI.Controls.Templates.IItemContainerTemplateSelector): }@if (wpf) { `ItemContainerTemplateSelector`: } +@if (avalonia) { +| ItemsControl | Expected Container Element(s) | +|-----|-----| +| [BarContextMenu](xref:@ActiproUIRoot.Controls.Bars.BarContextMenu) | Various [Bars controls](controls/index.md) for menu context. | +| [BarMenuGallery](xref:@ActiproUIRoot.Controls.Bars.BarMenuGallery) | [BarGalleryItem](xref:@ActiproUIRoot.Controls.Bars.BarGalleryItem). | +| [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) | Various [Bars controls](controls/index.md) for menu context. | +| [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton) | Various [Bars controls](controls/index.md) for menu context. | +| [BarSplitButton](xref:@ActiproUIRoot.Controls.Bars.BarSplitButton) | Various [Bars controls](controls/index.md) for menu context. | +| [BarSplitMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarSplitMenuItem) | Various [Bars controls](controls/index.md) for menu context. | +| [BarSplitToggleButton](xref:@ActiproUIRoot.Controls.Bars.BarSplitToggleButton) | Various [Bars controls](controls/index.md) for menu context. | +| [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) | [RibbonTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonTabItem). | +| [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage) | [RibbonBackstageTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageTabItem), [RibbonBackstageHeaderButton](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageHeaderButton), or [RibbonBackstageHeaderSeparator](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageHeaderSeparator). | +| [RibbonContextualTabGroupItemsControl](xref:@ActiproUIRoot.Controls.Bars.Primitives.RibbonContextualTabGroupItemsControl) | [RibbonContextualTabGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonContextualTabGroup). | +| [RibbonControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonControlGroup) | Various [Bars controls](controls/index.md) for ribbon context. | +| [RibbonGallery](xref:@ActiproUIRoot.Controls.Bars.RibbonGallery) | [BarGalleryItem](xref:@ActiproUIRoot.Controls.Bars.BarGalleryItem). | +| [RibbonGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonGroup) | [RibbonControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonControlGroup), [RibbonMultiRowControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonMultiRowControlGroup), or various [Bars controls](controls/index.md) for ribbon context. | +| [RibbonMultiRowControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonMultiRowControlGroup) | [RibbonControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonControlGroup) or various [Bars controls](controls/index.md) for ribbon context. | +| [RibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBar) | Various [Bars controls](controls/index.md) for ribbon context. | +| [RibbonTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonTabItem) | [RibbonGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonGroup). | +| [RibbonTabRowToolBar](xref:@ActiproUIRoot.Controls.Bars.RibbonTabRowToolBar) | Various [Bars controls](controls/index.md) for toolbar context. | +| [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar) | Various [Bars controls](controls/index.md) for toolbar context. | +| [TaskTabControl](xref:@ActiproUIRoot.Controls.Bars.TaskTabControl) | [TaskTabItem](xref:@ActiproUIRoot.Controls.Bars.TaskTabItem). | +} +@if (wpf) { | ItemsControl | Expected Container Element(s) | |-----|-----| | [BarContextMenu](xref:@ActiproUIRoot.Controls.Bars.BarContextMenu) | Various [Bars controls](controls/index.md) for menu context. | @@ -107,12 +177,17 @@ This table summarizes most of the `ItemsControl`-based controls in Bars and whic | [RibbonTabRowToolBar](xref:@ActiproUIRoot.Controls.Bars.RibbonTabRowToolBar) | Various [Bars controls](controls/index.md) for toolbar context. | | [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar) | Various [Bars controls](controls/index.md) for toolbar context. | | [TaskTabControl](xref:@ActiproUIRoot.Controls.Bars.TaskTabControl) | [TaskTabItem](xref:@ActiproUIRoot.Controls.Bars.TaskTabItem). | - +} ## Open Source MVVM Library The full source of the helpful companion MVVM library that contains Bars-related view model classes, template selector classes, and related view templates is available in GitHub at: +@if (avalonia) { +https://github.com/Actipro/Avalonia-Controls/tree/main/Source/Bars.Mvvm +} +@if (wpf) { https://github.com/Actipro/WPF-Controls/tree/main/Source/Bars.Mvvm +} If you wish for your Bars controls to be managed with MVVM, but don't wish to use our pre-built MVVM library, its source code is still an excellent reference for how you can integrate custom view models, template selectors, and templates with Bars controls. @@ -122,21 +197,21 @@ The MVVM library contains many types and templates to assist in managing Bars co ### Template Selectors -As described earlier in this topic, the Bars product has been designed to make use of `ItemContainerTemplateSelector` and `DataTemplateSelector` instances to associate view models with related view templates. The MVVM library includes numerous view model types and offers several template selectors classes that map the view models to predefined view templates. +As described earlier in this topic, the Bars product has been designed to make use of @if (avalonia) { [IItemContainerTemplateSelector](xref:ActiproSoftware.UI.Controls.Templates.IItemContainerTemplateSelector) and [IDataTemplateSelector](xref:ActiproSoftware.UI.Controls.Templates.IDataTemplateSelector) }@if (wpf) { `ItemContainerTemplateSelector` and `DataTemplateSelector` } instances to associate view models with related view templates. The MVVM library includes numerous view model types and offers several template selectors classes that map the view models to predefined view templates. #### For Bar Controls -The [BarControlTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarControlTemplateSelector) class inherits `ItemContainerTemplateSelector` and helps generate "container" elements for all of the bar control view models described later in this topic. +The [BarControlTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarControlTemplateSelector) class @if (avalonia) { implements [IItemContainerTemplateSelector](xref:ActiproSoftware.UI.Controls.Templates.IItemContainerTemplateSelector) }@if (wpf) { inherits `ItemContainerTemplateSelector` } and helps generate "container" elements for all of the bar control view models described later in this topic. When using the MVVM library with Bars controls, an instance of [BarControlTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarControlTemplateSelector) should be set to the root bar control's `ItemContainerTemplateSelector` property, such as [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[ItemContainerTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Ribbon.ItemContainerTemplateSelector) or [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar).[ItemContainerTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar.ItemContainerTemplateSelector). The template selector will propagate down the hierarchy of bar controls automatically. #### For Ribbon Footer Content -The [RibbonFooterContentTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterContentTemplateSelector) class inherits `DataTemplateSelector` and provides the view `DataTemplate` to use for ribbon footer content view models described later in this topic that are passed into the [RibbonFooterViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel).[Content](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel.Content) property. An instance of the template selector class is automatically assigned to the [RibbonFooterViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel).[ContentTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel.ContentTemplateSelector) property. +The [RibbonFooterContentTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterContentTemplateSelector) class @if (avalonia) { implements [IDataTemplateSelector](xref:ActiproSoftware.UI.Controls.Templates.IDataTemplateSelector) }@if (wpf) { inherits `DataTemplateSelector` } and provides the view @if (avalonia) { `IDataTemplate` }@if (wpf) { `DataTemplate` } to use for ribbon footer content view models described later in this topic that are passed into the [RibbonFooterViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel).[Content](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel.Content) property. An instance of the template selector class is automatically assigned to the [RibbonFooterViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel).[ContentTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel.ContentTemplateSelector) property. #### For Gallery Items -The [BarGalleryItemTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryItemTemplateSelector) class inherits `DataTemplateSelector` and provides the view `DataTemplate` to use for gallery item view models described later in this topic. An instance of the template selector needs to be assigned to each gallery control, which can be done through the [BarGalleryViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryViewModel).[ItemTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryViewModelBase.ItemTemplateSelector) property. +The [BarGalleryItemTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryItemTemplateSelector) class @if (avalonia) { implements [IDataTemplateSelector](xref:ActiproSoftware.UI.Controls.Templates.IDataTemplateSelector) }@if (wpf) { inherits `DataTemplateSelector` } and provides the view @if (avalonia) { `IDataTemplate` }@if (wpf) { `DataTemplate` } to use for gallery item view models described later in this topic. An instance of the template selector needs to be assigned to each gallery control, which can be done through the [BarGalleryViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryViewModel).[ItemTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryViewModelBase.ItemTemplateSelector) property. ### View Models @@ -146,6 +221,39 @@ The MVVM library contains many view models that can drive the various Bars contr The following table shows various bar control view model types defined in the MVVM library, and maps them to the control concepts they are pre-configured to generate via a [BarControlTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarControlTemplateSelector) instance. +@if (avalonia) { +| Name | Description | +|-----|-----| +| [BarButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarButtonViewModel) | Regular [button](controls/button.md) control. | +| [BarCheckBoxViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarCheckBoxViewModel) | [Checkbox](controls/checkbox.md) control. | +| [BarComboBoxViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarComboBoxViewModel) | [Combobox](controls/combobox.md) control. | +| [BarGalleryViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryViewModel) | [Gallery](controls/gallery.md) control. | +| [BarHeadingViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarHeadingViewModel) | [Heading](controls/heading.md) control. | +| [BarKeyedObjectViewModelBase](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarKeyedObjectViewModelBase) | Abstract base class for a [control with a string keys](controls/control-basics.md). | +| [BarPopupButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarPopupButtonViewModel) | [Popup button](controls/popup-button.md) control. | +| [BarSeparatorViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarSeparatorViewModel) | [Separator](controls/separator.md) control. | +| [BarSizeSelectionMenuGalleryViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarSizeSelectionMenuGalleryViewModel) | Size-selection [gallery](controls/gallery.md) control. | +| [BarSplitButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarSplitButtonViewModel) | Regular [split button](controls/split-button.md) control. | +| [BarSplitToggleButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarSplitToggleButtonViewModel) | Toggle [split button](controls/split-button.md) control. | +| [BarTextBoxViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarTextBoxViewModel) | [Textbox](controls/textbox.md) control. | +| [BarToggleButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarToggleButtonViewModel) | Toggle [button](controls/button.md) control. | +| [RibbonApplicationButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonApplicationButtonViewModel) | [Application button](ribbon-features/application-button.md) control. | +| [RibbonBackstageHeaderButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonBackstageHeaderButtonViewModel) | [Backstage](ribbon-features/backstage.md) header button control. | +| [RibbonBackstageHeaderSeparatorViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonBackstageHeaderSeparatorViewModel) | [Backstage](ribbon-features/backstage.md) header separator control. | +| [RibbonBackstageTabViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonBackstageTabViewModel) | [Backstage](ribbon-features/backstage.md) tab control. | +| [RibbonContextualTabGroupViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonContextualTabGroupViewModel) | [Contextual tab group](ribbon-features/contextual-tabs.md) control. | +| [RibbonControlGroupViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonControlGroupViewModel) | [Control group](ribbon-features/tabs-groups-controlgroups.md) control. | +| [RibbonFooterViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel) | [Footer](ribbon-features/footer.md) control. | +| [RibbonGroupLauncherButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonGroupLauncherButtonViewModel) | [Group launcher button](ribbon-features/tabs-groups-controlgroups.md) control. | +| [RibbonGroupViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonGroupViewModel) | [Group](ribbon-features/tabs-groups-controlgroups.md) control. | +| [RibbonMultiRowControlGroupViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonMultiRowControlGroupViewModel) | [Multi-row control group](ribbon-features/tabs-groups-controlgroups.md) control. | +| [RibbonQuickAccessToolBarViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonQuickAccessToolBarViewModel) | [Quick access toolbar](ribbon-features/quick-access-toolbar.md) control. | +| [RibbonTabRowToolBarViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonTabRowToolBarViewModel) | [Tab row toolbar](ribbon-features/tab-row-toolbar.md) control. | +| [RibbonTabViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonTabViewModel) | [Tab](ribbon-features/tabs-groups-controlgroups.md) control. | +| [RibbonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonViewModel) | [Ribbon](ribbon-features/index.md) control. | +| [StandaloneToolBarViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.StandaloneToolBarViewModel) | [Standalone toolbar](toolbar-features/standalone-toolbars.md) control. | +} +@if (wpf) { | Name | Description | |-----|-----| | [BarButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarButtonViewModel) | Regular [button](controls/button.md) control. | @@ -162,7 +270,7 @@ The following table shows various bar control view model types defined in the MV | [BarTextBoxViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarTextBoxViewModel) | [Textbox](controls/textbox.md) control. | | [BarToggleButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarToggleButtonViewModel) | Toggle [button](controls/button.md) control. | | [MiniToolBarViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.MiniToolBarViewModel) | [Mini-toolbar](toolbar-features/mini-toolbars.md) control. | -| [RibbonApplicationButton](xref:@ActiproUIRoot.Controls.Bars.RibbonApplicationButton) | [Application button](ribbon-features/application-button.md) control. | +| [RibbonApplicationButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonApplicationButtonViewModel) | [Application button](ribbon-features/application-button.md) control. | | [RibbonBackstageHeaderButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonBackstageHeaderButtonViewModel) | [Backstage](ribbon-features/backstage.md) header button control. | | [RibbonBackstageHeaderSeparatorViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonBackstageHeaderSeparatorViewModel) | [Backstage](ribbon-features/backstage.md) header separator control. | | [RibbonBackstageTabViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonBackstageTabViewModel) | [Backstage](ribbon-features/backstage.md) tab control. | @@ -177,6 +285,7 @@ The following table shows various bar control view model types defined in the MV | [RibbonTabViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonTabViewModel) | [Tab](ribbon-features/tabs-groups-controlgroups.md) control. | | [RibbonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonViewModel) | [Ribbon](ribbon-features/index.md) control. | | [StandaloneToolBarViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.StandaloneToolBarViewModel) | [Standalone toolbar](toolbar-features/standalone-toolbars.md) control. | +} > [!NOTE] > Some view models may generate a different control based on the usage context. For instance, a [BarButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarButtonViewModel) will generate a [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton) control when in a ribbon/toolbar context, and a [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) control when in a menu context. @@ -187,8 +296,8 @@ The following table shows the ribbon footer content view model types defined in | Name | Description | |-----|-----| -| [RibbonFooterInfoBarContentViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterInfoBarContentViewModel) | Configures an [InfoBar](../shared/windows-controls/info-bar.md) to render in the ribbon [footer](ribbon-features/footer.md) | -| [RibbonFooterSimpleContentViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterSimpleContentViewModel) | Specifies an `ImageSource` and text message to render in the ribbon [footer](ribbon-features/footer.md). | +| [RibbonFooterInfoBarContentViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterInfoBarContentViewModel) | Configures an @if (avalonia) { [InfoBar](../fundamentals/controls/info-bar.md) }@if (wpf) { [InfoBar](../shared/windows-controls/info-bar.md) } to render in the ribbon [footer](ribbon-features/footer.md) | +| [RibbonFooterSimpleContentViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterSimpleContentViewModel) | Specifies an @if (avalonia) { `IImage` }@if (wpf) { `ImageSource` } and text message to render in the ribbon [footer](ribbon-features/footer.md). | #### Gallery Item View Models @@ -228,6 +337,32 @@ By default, the [Label](xref:@ActiproUIRoot.Controls.Bars.Mvvm.IBarGalleryItemVi > [!TIP] > Use the [EnumBarGalleryItemViewModel\](xref:@ActiproUIRoot.Controls.Bars.Mvvm.EnumBarGalleryItemViewModel`1).[CreateCollection](xref:@ActiproUIRoot.Controls.Bars.Mvvm.EnumBarGalleryItemViewModel`1.CreateCollection*) method to easily populate a [Combobox](controls/combobox.md) with all the available values of an enumeration. +@if (avalonia) { +### Root Bar Control Themes + +The [BarsMvvmResourceKeys](xref:@ActiproUIRoot.Themes.Bars.Mvvm.BarsMvvmResourceKeys) class provides access to keys of several pre-configured `ControlTheme` instances in `Resources` that bind root bar controls to their related view model. It is assumed that the appropriate view model is set to the bar control's `DataContext` property in your code. + +| Property Name | Description | +|-----|-----| +| [RibbonControlTheme](xref:@ActiproUIRoot.Themes.Bars.Mvvm.BarsMvvmResourceKeys.RibbonControlTheme) | Sets up bindings on a [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) control to a [RibbonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonViewModel) instance. | +| [StandaloneToolBarControlTheme](xref:@ActiproUIRoot.Themes.Bars.Mvvm.BarsMvvmResourceKeys.StandaloneToolBarControlTheme) | Sets up bindings on a [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar) control to a [StandaloneToolBarViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.StandaloneToolBarViewModel) instance. | + +> [!TIP] +> It is recommended that these control themes are used on the root bar controls when using the MVVM library. + +This example shows how to use a root bar control `ControlTheme` on a [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon): + +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + +``` +} +@if (wpf) { + ### Root Bar Control Styles The [BarsMvvmResourceKeys](xref:@ActiproUIRoot.Themes.BarsMvvmResourceKeys) class provides access to several pre-configured `Style` instances in `Resources` that bind root bar controls to their related view model. It is assumed that the appropriate view model is set to the bar control's `DataContext` property in your code. @@ -251,6 +386,7 @@ xmlns:themes="http://schemas.actiprosoftware.com/winfx/xaml/themes" Style="{StaticResource {x:Static themes:BarsMvvmResourceKeys.RibbonStyle}}" /> ``` +} ### Bar Image Provider @@ -260,7 +396,7 @@ The [BarImageOptions](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarImageOptions) cl The [BarImageProvider](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarImageProvider) class implements [IBarImageProvider](xref:@ActiproUIRoot.Controls.Bars.Mvvm.IBarImageProvider) and allows you to [Register](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarImageProvider.Register*) an image factory function for a string key. The key should generally match the key for the related bar control. -The factory function is called when the [GetImageSource](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarImageProvider.GetImageSource*) method is invoked and passes a [BarImageOptions](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarImageOptions) instance, while expecting an `ImageSource` in return. +The factory function is called when the [GetImageSource](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarImageProvider.GetImageSource*) method is invoked and passes a [BarImageOptions](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarImageOptions) instance, while expecting an @if (avalonia) { `IImage` }@if (wpf) { `ImageSource` } in return. This example demonstrates a registration, and assumes your application has an `ImageLoader.GetIcon` method that loads the image with the specified filename: @@ -280,8 +416,8 @@ For instance, say the [BarButtonViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvv ### Third-Party Control Support -In another scenario, perhaps you wish to introduce a brand-new bar control view model class for a third-party control. Create a view model class with the properties you wish to bind to the control. Next, create a class that inherits [BarControlTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarControlTemplateSelector) and override its `SelectTemplate` method to handle the new view model as an item. It should return a new `DataTemplate` that contains the third-party control and appropriate bindings to the view model. Be sure to call the base `SelectTemplate` method for other bar control view model types so they are still handled properly. Set an instance of the custom [BarControlTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarControlTemplateSelector)-based class to all root bar controls like [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) or [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar). +In another scenario, perhaps you wish to introduce a brand-new bar control view model class for a third-party control. Create a view model class with the properties you wish to bind to the control. Next, create a class that inherits [BarControlTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarControlTemplateSelector) and override its `SelectTemplate` method to handle the new view model as an item. It should return a new @if (avalonia) { `IDataTemplate` }@if (wpf) { `DataTemplate` } that contains the third-party control and appropriate bindings to the view model. Be sure to call the base `SelectTemplate` method for other bar control view model types so they are still handled properly. Set an instance of the custom [BarControlTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarControlTemplateSelector)-based class to all root bar controls like [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) or [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar). ### New Gallery Item Kind Support -The most common customization is likely for gallery items since these tend to be more application specific. When creating a new kind of gallery item, create a view model class that inherits [BarGalleryItemViewModel\](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryItemViewModel`1) and has whatever other properties are necessary for the gallery item to be identifiable and capable of rendering in UI. Next, create a class that inherits [BarGalleryItemTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryItemTemplateSelector) and override its `SelectTemplate` method to handle the new view model as an item. It should return a new `DataTemplate` that contains the UI elements used to render the gallery item, along with appropriate bindings to the view model. Be sure to call the base `SelectTemplate` method for other gallery item view model types so they are still handled properly. Set an instance of the custom [BarGalleryItemTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryItemTemplateSelector)-based class to any galleries that host the new kind of gallery item. +The most common customization is likely for gallery items since these tend to be more application specific. When creating a new kind of gallery item, create a view model class that inherits [BarGalleryItemViewModel\](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryItemViewModel`1) and has whatever other properties are necessary for the gallery item to be identifiable and capable of rendering in UI. Next, create a class that inherits [BarGalleryItemTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryItemTemplateSelector) and override its `SelectTemplate` method to handle the new view model as an item. It should return a new @if (avalonia) { `IDataTemplate` }@if (wpf) { `DataTemplate` } that contains the UI elements used to render the gallery item, along with appropriate bindings to the view model. Be sure to call the base `SelectTemplate` method for other gallery item view model types so they are still handled properly. Set an instance of the custom [BarGalleryItemTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarGalleryItemTemplateSelector)-based class to any galleries that host the new kind of gallery item. diff --git a/Documentation/topics/bars/ribbon-features/application-button.md b/Documentation/topics/bars/ribbon-features/application-button.md index 75320ae6..3486d554 100644 --- a/Documentation/topics/bars/ribbon-features/application-button.md +++ b/Documentation/topics/bars/ribbon-features/application-button.md @@ -5,9 +5,14 @@ order: 20 --- # Application Button -Ribbon supports an application button that can open a menu that is generally populated by application-wide options such as **New**, **Open**, and **Save** operations. +@if (avalonia) { +Ribbon supports an application button that can open a [backstage](backstage.md) when the button is clicked. +} +@if (wpf) { +Ribbon supports an application button that can open a menu that is generally populated by application-wide options such as **New**, **Open**, and **Save**. Either a traditional [application menu](application-menu.md) or more modern [backstage](backstage.md) can be displayed when the button is clicked. See the respective topics for more details on configuring each style. +} The application button can also be hidden if a corresponding menu is not necessary or desired. @@ -24,6 +29,20 @@ The application button can be defined in XAML or code-behind by assigning a [Rib This code sample shows how to define the application button for a ribbon: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -35,6 +54,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ``` +} ## MVVM Support @@ -45,9 +65,16 @@ The optional companion [MVVM Library](../mvvm-support.md) defines a [RibbonAppli > [!TIP] > See the [MVVM Support](../mvvm-support.md) topic for more information on how to use the library's view models and view templates to create and manage your application's bars controls with MVVM techniques. +@if (avalonia) { +## Customizing the Application Button Theme + +The [RibbonApplicationButton](xref:@ActiproUIRoot.Controls.Bars.RibbonApplicationButton) instance can be customized by setting a `ControlTheme` to the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[ApplicationButtonTheme](xref:@ActiproUIRoot.Controls.Bars.Ribbon.ApplicationButtonTheme) property. This `ControlTheme` is applied to the control when it is added to the ribbon. +} +@if (wpf) { ## Customizing the Application Button Style The [RibbonApplicationButton](xref:@ActiproUIRoot.Controls.Bars.RibbonApplicationButton) instance can be customized by setting a `Style` to the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[ApplicationButtonStyle](xref:@ActiproUIRoot.Controls.Bars.Ribbon.ApplicationButtonStyle) property. This `Style` is applied to the control when it is added to the ribbon. +} ## Customizing Default Text @@ -67,6 +94,20 @@ See the [Customizing String Resources](../../customizing-string-resources.md) to As an alternative to customizing the string resource, the [RibbonApplicationButton](xref:@ActiproUIRoot.Controls.Bars.RibbonApplicationButton).[Label](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.Label) and [RibbonApplicationButton](xref:@ActiproUIRoot.Controls.Bars.RibbonApplicationButton).[KeyTipText](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarPopupButtonBase.KeyTipText) can be set directly to the desired value as illustrated in the following example: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -78,10 +119,33 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ``` +} ## Custom Button Content -The [RibbonApplicationButton](xref:@ActiproUIRoot.Controls.Bars.RibbonApplicationButton).[Content](xref:@ActiproUIRoot.Controls.Bars.RibbonApplicationButton.Content) property can be set to any `Object` which is supported by `ContentPresenter`, so custom content like an image can easily be used instead of text. The following example shows how to set an image for the content using a [DynamicImage](../../shared/windows-controls/dynamicimage.md). +@if (avalonia) { +The [RibbonApplicationButton](xref:@ActiproUIRoot.Controls.Bars.RibbonApplicationButton).`Content` property can be set to any `Object` which is supported by `ContentPresenter`, so custom content like an image can easily be used instead of text. The following example shows how to set an image for the content using a [DynamicImage](../../shared/controls/dynamic-image.md): + +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + + +``` +} +@if (wpf) { +The [RibbonApplicationButton](xref:@ActiproUIRoot.Controls.Bars.RibbonApplicationButton).[Content](xref:@ActiproUIRoot.Controls.Bars.RibbonApplicationButton.Content) property can be set to any `Object` which is supported by `ContentPresenter`, so custom content like an image can easily be used instead of text. The following example shows how to set an image for the content using a [DynamicImage](../../shared/windows-controls/dynamicimage.md): ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" @@ -101,13 +165,14 @@ xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared" ``` +} > [!TIP] > See the "Application Button" Bars Ribbon QuickStart of the Sample Browser application for a full demonstration of setting the button content. ## Hiding the Application Button -If your application does not need an [Application Menu](application-menu.md) or [Backstage](backstage.md), you may want to hide the application button completely by setting the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[IsApplicationButtonVisible](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsApplicationButtonVisible) property to `false`. +If your application does not need @if (wpf) { an [Application Menu](application-menu.md) or } a [Backstage](backstage.md), you may want to hide the application button completely by setting the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[IsApplicationButtonVisible](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsApplicationButtonVisible) property to `false`. ![Screenshot](../images/application-button-hidden.png) diff --git a/Documentation/topics/bars/ribbon-features/backstage.md b/Documentation/topics/bars/ribbon-features/backstage.md index c2335966..49a80528 100644 --- a/Documentation/topics/bars/ribbon-features/backstage.md +++ b/Documentation/topics/bars/ribbon-features/backstage.md @@ -9,15 +9,22 @@ The backstage was introduced in Office 2010 and can be displayed when clicking t ![Screenshot](../images/backstage-buttons.png) +@if (avalonia) { +*A backstage with styled buttons* +} +@if (wpf) { *A backstage with styled buttons and backdrop effect* +} The backstage is organized such that buttons and tabs appear on the near side (the header area) and the selected tab's content appears on the far side (the content area). +@if (wpf) { > [!IMPORTANT] > A ribbon must be hosted within a [RibbonWindow](ribbon-window.md) and [RibbonContainerPanel](xref:@ActiproUIRoot.Controls.Bars.RibbonContainerPanel) to support the backstage taking over the entire window. > [!NOTE] > See the [Application Menu](application-menu.md) topic for details on how to define a more traditional application menu instead of a backstage. +} ## Defining a Backstage @@ -28,6 +35,40 @@ The backstage can be defined in XAML or code-behind by assigning a [RibbonBackst This code sample shows how to define a backstage for a ribbon. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -59,10 +100,14 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ``` +} +@if (wpf) { > [!IMPORTANT] > The [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) that defines a backstage should be a child of a [RibbonContainerPanel](xref:@ActiproUIRoot.Controls.Bars.RibbonContainerPanel) for the backstage to display properly. When a backstage is opened, it will cover the entire area defined by the [RibbonContainerPanel](xref:@ActiproUIRoot.Controls.Bars.RibbonContainerPanel) (with additional support when hosted inside a [RibbonWindow](xref:@ActiproUIRoot.Controls.Bars.RibbonWindow)). See the [Control Hierarchy](control-hierarchy.md) topic for more information on optionally defining the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) inside a `ContentControl`. +} +@if (wpf) { ## Header Area Transparency The backstage template is set up to use a transparent background in its tab header area when a system backdrop like Mica (available starting in Windows 11) is enabled on the containing `Window`'s [WindowChrome](../../themes/windowchrome.md). It is important to use the control hierarchy described above that involves [RibbonContainerPanel](xref:@ActiproUIRoot.Controls.Bars.RibbonContainerPanel), as the panel will hide when backstage is open, allowing the system backdrop background to show through to the backstage header area instead of content like a ribbon control that is underneath the backstage. @@ -72,6 +117,7 @@ In a scenario where there is other content outside of the panel that is showing When the containing window's chrome is not configured to use a system backdrop, or on pre-Windows 11 systems, the backstage header area will use an opaque background. See the [WindowChrome](../../themes/windowchrome.md) topic for complete details on the application and operating system requirements necessary to support transparency. +} ## MVVM Support @@ -82,15 +128,22 @@ The optional companion [MVVM Library](../mvvm-support.md) defines a [RibbonBacks > [!TIP] > See the [MVVM Support](../mvvm-support.md) topic for more information on how to use the library's view models and view templates to create and manage your application's bars controls with MVVM techniques. +@if (avalonia) { +## Customizing the Backstage Theme + +The [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage) instance can be customized by setting a `ControlTheme` to the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[BackstageTheme](xref:@ActiproUIRoot.Controls.Bars.Ribbon.BackstageTheme) property. This `ControlTheme` is applied to the control when it is added to the ribbon. +} +@if (wpf) { ## Customizing the Backstage Style The [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage) instance can be customized by setting a `Style` to the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[BackstageStyle](xref:@ActiproUIRoot.Controls.Bars.Ribbon.BackstageStyle) property. This `Style` is applied to the control when it is added to the ribbon. +} ## Defining Backstage Items The [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage) control can contain these types of controls, which appear vertically in its header area: [RibbonBackstageHeaderButton](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageHeaderButton), [RibbonBackstageTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageTabItem), and [RibbonBackstageHeaderSeparator](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageHeaderSeparator). -Controls will the same header alignment appear in the order in which they are defined in the [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage). This allows you to freely intermix the order of buttons, tabs, and any separators. By default, each item is aligned to the top but setting the control's `HeaderAlignment` property to [RibbonBackstageHeaderAlignment](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageHeaderAlignment).[Bottom](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageHeaderAlignment.Bottom) will shift the alignment to the bottom. +Controls with the same header alignment appear in the order in which they are defined in the [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage). This allows you to freely intermix the order of buttons, tabs, and any separators. By default, each item is aligned to the top but setting the control's `HeaderAlignment` property to [RibbonBackstageHeaderAlignment](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageHeaderAlignment).[Bottom](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageHeaderAlignment.Bottom) will shift the alignment to the bottom. ### Buttons @@ -125,7 +178,7 @@ Set the [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage).[Ca ## TaskTabControl -The [TaskTabControl](xref:@ActiproUIRoot.Controls.Bars.TaskTabControl) is a styled version of a native WPF `TabControl` that renders its tabs on the left side. The selected tab's content appears on the right side. This tab control is ideal for use on a [RibbonBackstageTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageTabItem) since it provides a secondary level of tabs. It can be used externally to backstage as well. +The [TaskTabControl](xref:@ActiproUIRoot.Controls.Bars.TaskTabControl) is a styled version of a native `TabControl` that renders its tabs on the left side. The selected tab's content appears on the right side. This tab control is ideal for use on a [RibbonBackstageTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageTabItem) since it provides a secondary level of tabs. It can be used externally to backstage as well. ![Screenshot](../images/backstage-controls.png) @@ -135,12 +188,30 @@ The items of a [TaskTabControl](xref:@ActiproUIRoot.Controls.Bars.TaskTabControl Use the [TaskTabItem](xref:@ActiproUIRoot.Controls.Bars.TaskTabItem).[Label](xref:@ActiproUIRoot.Controls.Bars.TaskTabItem.Label) and [TaskTabItem](xref:@ActiproUIRoot.Controls.Bars.TaskTabItem).[LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.TaskTabItem.LargeImageSource) properties to define the tab header. -## BarButton and BarPopupButton Styles +@if (avalonia) { +## Backstage Button Themes + +The backstage content area commonly uses large buttons. The various button controls ([BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton), [BarToggleButton](xref:@ActiproUIRoot.Controls.Bars.BarToggleButton), [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton), [BarSplitButton](xref:@ActiproUIRoot.Controls.Bars.BarSplitButton), and [BarSplitToggleButton](xref:@ActiproUIRoot.Controls.Bars.BarSplitToggleButton)) have special themes that can be applied to display as a large button.} +@if (wpf) { +## Backstage Button Styles The backstage content area commonly uses large buttons. Both the [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton) and [BarPopupButton](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton) controls have special styles that can be applied to display as a large button. +} -Use of those properties can trigger the style of buttons found in Office's Backstage, and as seen in the `TaskTabControl` screenshot above. The following example shows how to apply the styles: +Use of those @if (avalonia) { themes }@if (wpf) { styles } results in buttons with an appearance similar to Office's Backstage, and as seen in the `TaskTabControl` screenshot above. The following example shows how to apply the @if (avalonia) { themes }@if (wpf) { styles }: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" xmlns:themes="http://schemas.actiprosoftware.com/winfx/xaml/themes" @@ -148,6 +219,7 @@ xmlns:themes="http://schemas.actiprosoftware.com/winfx/xaml/themes" ``` +} ## Preventing Backstage from Closing diff --git a/Documentation/topics/bars/ribbon-features/collapsing.md b/Documentation/topics/bars/ribbon-features/collapsing.md index 6b1a4684..12fb3e2f 100644 --- a/Documentation/topics/bars/ribbon-features/collapsing.md +++ b/Documentation/topics/bars/ribbon-features/collapsing.md @@ -15,8 +15,14 @@ The ribbon is capable of collapsing when it becomes smaller than a threshold siz *The ribbon in a collapsed state* +@if (avalonia) { +> [!TIP] +> The automatic collapsing behavior can be disabled. +} +@if (wpf) { > [!TIP] > The automatic collapsing behavior can be disabled, and the threshold size can be configured. +} > [!IMPORTANT] > "Minimized" and "Collapsed" are two separate concepts for ribbon that are easy to confuse. "Minimized" indicates only the ribbon tabs are visible whereas "Collapsed" means the entire ribbon is hidden. See the [Minimization](minimization.md) topic for more details. @@ -25,9 +31,18 @@ The ribbon is capable of collapsing when it becomes smaller than a threshold siz The [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) defines several members that relate to collapsing. +@if (avalonia) { +| Member | Description | +|-----|-----| +| [IsCollapsed](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsCollapsed) Property | Gets or sets whether the ribbon is currently collapsed. This property should not need to be called by your code under normal circumstances. | +| [IsCollapsedChanged](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsCollapsedChanged) Event | Occurs when the [IsCollapsed](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsCollapsed) property value has changed. | +| [IsCollapsible](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsCollapsible) Property | Gets or sets whether the ribbon collapses when it becomes smaller than a minimum threshold. | +} +@if (wpf) { | Member | Description | |-----|-----| | [CollapseThresholdSize](xref:@ActiproUIRoot.Controls.Bars.Ribbon.CollapseThresholdSize) Property | Gets or sets the threshold `Size` that triggers a ribbon collapse if the ribbon is sized smaller than the threshold. The default threshold size is `270, 170`. | | [IsCollapsed](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsCollapsed) Property | Gets or sets whether the ribbon is currently collapsed. This property should not need to be called by your code under normal circumstances. | | [IsCollapsedChanged](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsCollapsedChanged) Event | Occurs when the [IsCollapsed](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsCollapsed) property value has changed. | | [IsCollapsible](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsCollapsible) Property | Gets or sets whether the ribbon collapses when it becomes smaller than a minimum threshold width/height as specified by the [CollapseThresholdSize](xref:@ActiproUIRoot.Controls.Bars.Ribbon.CollapseThresholdSize) property. | +} \ No newline at end of file diff --git a/Documentation/topics/bars/ribbon-features/contextual-tabs.md b/Documentation/topics/bars/ribbon-features/contextual-tabs.md index 84b89c77..f267d769 100644 --- a/Documentation/topics/bars/ribbon-features/contextual-tabs.md +++ b/Documentation/topics/bars/ribbon-features/contextual-tabs.md @@ -23,6 +23,42 @@ See the [Tabs, Groups, and Control Groups](tabs-groups-controlgroups.md) topic f The following code sample shows how to define two contextual tab groups for a ribbon (`PictureTools` and `TableTools`) and then associate tabs with the corresponding group: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + + + ... + + + + + ... + + + + + ... + + + ... + + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -56,15 +92,38 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ``` +} ## Showing / Hiding a Contextual Tab Group +@if (avalonia) { +The [RibbonContextualTabGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonContextualTabGroup).`IsVisible` property determines the visibility of the associated [tab](tabs-groups-controlgroups.md) controls. + +When the [RibbonContextualTabGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonContextualTabGroup).`IsVisible` property is set to `true`, all its associated [tab](tabs-groups-controlgroups.md) controls are displayed. Likewise, setting the `IsVisible` property to `false` hides all its associated tabs. Multiple contextual tab groups can be visible at the same time. +} +@if (wpf) { The [RibbonContextualTabGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonContextualTabGroup).`Visibility` property determines the visibility of the associated [tab](tabs-groups-controlgroups.md) controls. When the [RibbonContextualTabGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonContextualTabGroup).`Visibility` property is set to `Visible`, all its associated [tab](tabs-groups-controlgroups.md) controls are displayed. Likewise, setting the `Visibility` property to `Collapsed` hides all its associated tabs. Multiple contextual tab groups can be visible at the same time. +} The following code sample demonstrates one way to show all the tabs associated with a [RibbonContextualTabGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonContextualTabGroup): +@if (avalonia) { +```csharp +using ActiproSoftware.UI.Avalonia.Controls.Bars; +using System.Linq; +... +Ribbon ribbon; +... +var pictureToolsGroup = ribbon.ContextualTabGroups + .OfType() + .FirstOrDefault(group => group.Key == "PictureTools") +if (pictureToolsGroup != null) + pictureToolsGroup.IsVisible = true; +``` +} +@if (wpf) { ```csharp using ActiproSoftware.Windows.Controls.Bars; using System.Linq; @@ -77,6 +136,7 @@ var pictureToolsGroup = ribbon.ContextualTabGroups if (pictureToolsGroup != null) pictureToolsGroup.Visibility = System.Windows.Visibility.Visible; ``` +} > [!TIP] > See the "Contextual Tabs" Bars Ribbon QuickStart of the Sample Browser application for a full demonstration of working with contextual tabs. \ No newline at end of file diff --git a/Documentation/topics/bars/ribbon-features/control-hierarchy.md b/Documentation/topics/bars/ribbon-features/control-hierarchy.md index b8781d98..a3a06be0 100644 --- a/Documentation/topics/bars/ribbon-features/control-hierarchy.md +++ b/Documentation/topics/bars/ribbon-features/control-hierarchy.md @@ -25,10 +25,28 @@ For composible UI frameworks like Prism, it may not be reasonable to define a `R The following sample demonstrates how a `ContentControl` might be configured within a `RibbonContainerPanel`: +@if (avalonia) { ```xaml -xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" -... - + + + + + + + + + + + + + ``` +} +@if (wpf) { +```xaml + + @@ -37,12 +55,13 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" + ``` + } In the code-behind, the `ribbonContent.Content` should be assigned an instance of `Ribbon`. - ## Ribbon The following hierarchy shows the definition of a [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) control and the typical types (with their own hierarchies) that are assigned to important properties. @@ -50,6 +69,46 @@ The following hierarchy shows the definition of a [Ribbon](xref:@ActiproUIRoot.C > [!NOTE] > Any `ItemsControl` listed below that does not explicitly identify a property as a child in the hierarchy should be assumed to be the `Items` or `ItemsSource` property. Likewise, the child of a `ContentControl` should be assumed to be the `Content` property. +@if (avalonia) { +- [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) : `ItemsControl` + - [QuickAccessToolBarContent](xref:@ActiproUIRoot.Controls.Bars.Ribbon.QuickAccessToolBarContent) : `object` *(see [Quick Access Toolbar](quick-access-toolbar.md) topic)* + - [RibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBar) : `ItemsControl` + - [CommonItems](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBar.CommonItems) : `IEnumerable` + - *Toolbar controls (e.g., `BarButton`... see "Toolbar Controls" section)* + - `ItemsControl.Items` + - *Toolbar controls (e.g., `BarButton`... see "Toolbar Controls" section)* + - [ApplicationButtonContent](xref:@ActiproUIRoot.Controls.Bars.Ribbon.ApplicationButtonContent) : `object` *(see [Application Button](application-button.md) topic)* + - [RibbonApplicationButton](xref:@ActiproUIRoot.Controls.Bars.RibbonApplicationButton) : `Button` + - [BackstageContent](xref:@ActiproUIRoot.Controls.Bars.Ribbon.BackstageContent) : `object` *(see [Backstage](backstage.md) topic)* + - [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage) : `TabControl`, `ItemsControl` + - [RibbonBackstageTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageTabItem) : `TabItem` + - `ContentControl.Content` *(commonly used backstage controls listed below)* + - [TaskTabControl](xref:@ActiproUIRoot.Controls.Bars.TaskTabControl) : `TabControl`, `ItemsControl` + - [TaskTabItem](xref:@ActiproUIRoot.Controls.Bars.TaskTabItem) : `TabItem` + - [RecentDocumentControl](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl) : `ItemsControl` *(see [Recent Documents](recent-documents.md) topic)* + - [RecentDocumentItem](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentItem) : `Button` + - `BarButton`, `BarPopupButton` *(with backstage styles applied)* + - *Any object* + - [RibbonBackstageHeaderButton](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageHeaderButton) : `Button` + - [RibbonBackstageHeaderSeparator](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageHeaderSeparator) : `Separator` + - [FooterContent](xref:@ActiproUIRoot.Controls.Bars.Ribbon.FooterContent) : `object` *(see [Footer](footer.md) topic)* + - [RibbonFooterControl](xref:@ActiproUIRoot.Controls.Bars.RibbonFooterControl) : `ContentControl` + - *Any object* + - [TabRowToolBarContent](xref:@ActiproUIRoot.Controls.Bars.Ribbon.TabRowToolBarContent) : `object` (see [Tab Row Toolbar](tab-row-toolbar.md) topic) + - [RibbonTabRowToolBar](xref:@ActiproUIRoot.Controls.Bars.RibbonTabRowToolBar) : `ItemsControl` + - *Toolbar controls (e.g., `BarButton`... see "Toolbar Controls" section)* + - [ContextualTabGroups](xref:@ActiproUIRoot.Controls.Bars.Ribbon.ContextualTabGroups) : `IEnumerable` *(see [Contextual Tabs](contextual-tabs.md) topic)* + - [RibbonContextualTabGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonContextualTabGroup) : `Control` + - `ItemsControl.Items` + - [RibbonTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonTabItem) : `ItemsControl` *(see [Tabs, Groups, and Control Groups](tabs-groups-controlgroups.md) topic)* + - [RibbonGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonGroup) : `ItemsControl` *(see [Tabs, Groups, and Control Groups](tabs-groups-controlgroups.md) topic)* + - [RibbonControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonControlGroup) : `ItemsControl` *(see [Tabs, Groups, and Control Groups](tabs-groups-controlgroups.md) topic)* + - *Toolbar controls (e.g., `BarButton`... see "Toolbar Controls" section)* + - [RibbonMultiRowControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonMultiRowControlGroup) : `ItemsControl` *(see [Tabs, Groups, and Control Groups](tabs-groups-controlgroups.md) topic)* + - [RibbonControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonControlGroup) *or toolbar controls (e.g., `BarButton`... see "Toolbar Controls" section)* + - *Toolbar controls (e.g., `BarButton`... see "Toolbar Controls" section)* +} +@if (wpf) { - [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) : `ItemsControl` - [QuickAccessToolBarContent](xref:@ActiproUIRoot.Controls.Bars.Ribbon.QuickAccessToolBarContent) : `object` *(see [Quick Access Toolbar](quick-access-toolbar.md) topic)* - [RibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBar) : `ItemsControl` @@ -95,7 +154,7 @@ The following hierarchy shows the definition of a [Ribbon](xref:@ActiproUIRoot.C - [RibbonMultiRowControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonMultiRowControlGroup) : `ItemsControl` *(see [Tabs, Groups, and Control Groups](tabs-groups-controlgroups.md) topic)* - [RibbonControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonControlGroup) *or toolbar controls (e.g., `BarButton`... see "Toolbar Controls" section)* - *Toolbar controls (e.g., `BarButton`... see "Toolbar Controls" section)* - +} ### Toolbar Controls The following controls can appear within the context of a toolbar and show their respective hierarchies: diff --git a/Documentation/topics/bars/ribbon-features/footer.md b/Documentation/topics/bars/ribbon-features/footer.md index c593eca4..f240c21c 100644 --- a/Documentation/topics/bars/ribbon-features/footer.md +++ b/Documentation/topics/bars/ribbon-features/footer.md @@ -20,6 +20,29 @@ The footer can be defined in XAML or code-behind by assigning a [RibbonFooterCon The following example demonstrates defining a footer message with an icon. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared" @@ -41,6 +64,7 @@ xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared" ``` +} ## MVVM Support @@ -54,10 +78,10 @@ A [RibbonFooterSimpleContentViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.Ri ### InfoBar Content -A [RibbonFooterInfoBarContentViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterInfoBarContentViewModel) instance may be assigned to the [RibbonFooterViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel).[Content](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel.Content) property. This view model supports configuring an [InfoBar](../../shared/windows-controls/info-bar.md) for the footer. +A [RibbonFooterInfoBarContentViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterInfoBarContentViewModel) instance may be assigned to the [RibbonFooterViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel).[Content](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel.Content) property. This view model supports configuring an @if (avalonia) { [InfoBar](../../fundamentals/controls/info-bar.md) }@if (wpf) { [InfoBar](../../shared/windows-controls/info-bar.md) } for the footer. > [!IMPORTANT] -> The [RibbonFooterViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel).[Padding](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel.Padding) property should be set to `0` when using [RibbonFooterInfoBarContentViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterInfoBarContentViewModel) as the content so the [InfoBar](../../shared/windows-controls/info-bar.md) can render edge-to-edge. +> The [RibbonFooterViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel).[Padding](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel.Padding) property should be set to `0` when using [RibbonFooterInfoBarContentViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterInfoBarContentViewModel) as the content so the @if (avalonia) { [InfoBar](../../fundamentals/controls/info-bar.md) }@if (wpf) { [InfoBar](../../shared/windows-controls/info-bar.md) } can render edge-to-edge. > [!TIP] > See the [MVVM Support](../mvvm-support.md) topic for more information on how to use the library's view models and view templates to create and manage your application's bars controls with MVVM techniques. @@ -73,28 +97,24 @@ The ribbon will display the footer as long as the [Ribbon](xref:@ActiproUIRoot.C By default, the footer background will use a color that is consistent with the ribbon theme, but any brush can be assigned to the [RibbonFooterControl](xref:@ActiproUIRoot.Controls.Bars.RibbonFooterControl).`Background` property to customize the appearance. For example, a different color might be used to indicate the severity of a message or to simply draw attention to the footer area. - Instead of setting the `Background` property directly, the [RibbonFooterControl](xref:@ActiproUIRoot.Controls.Bars.RibbonFooterControl).[Kind](xref:@ActiproUIRoot.Controls.Bars.RibbonFooterControl.Kind) property can be set one of the [RibbonFooterKind](xref:@ActiproUIRoot.Controls.Bars.RibbonFooterKind) values to trigger a pre-defined background brush. This is the recommended approach for customizing the background since the resulting brush asset will be consistent with the current theme. -See the [Reusable Assets](../../themes/reusable-assets.md) topic for details on customizing the pre-defined brush assets used by a footer kind. - -> [!TIP] -> See the "Footer" Bars Ribbon QuickStart of the Sample Browser application for a full demonstration of working with the ribbon footer. +See the @if (avalonia) { [Theme Assets](../../themes/theme-assets.md) }@if (wpf) { [Reusable Assets](../../themes/reusable-assets.md) } topic for details on customizing the pre-defined brush assets used by a footer kind. ## Using InfoBar in the Footer -The [InfoBar](../../shared/windows-controls/info-bar.md) is specifically designed to display non-intrusive user messages and is a natural fit for use in the footer, but some properties should be changed to optimally display the control. +The @if (avalonia) { [InfoBar](../../fundamentals/controls/info-bar.md) }@if (wpf) { [InfoBar](../../shared/windows-controls/info-bar.md) } is specifically designed to display non-intrusive user messages and is a natural fit for use in the footer, but some properties should be changed to optimally display the control. - **BorderThickness** - Set [InfoBar](xref:@ActiproUIRoot.Controls.InfoBar).`BorderThickness` to `0` since the footer already defines a border. - **IsAnimationEnabled** - The ribbon already animates when a footer is opened/closed, so set [InfoBar](xref:@ActiproUIRoot.Controls.InfoBar).[IsAnimationEnabled](xref:@ActiproUIRoot.Controls.InfoBar.IsAnimationEnabled) to `false`. ### Padding -Since the [InfoBar](../../shared/windows-controls/info-bar.md) should fill the entire area of the footer, it is important to set the [RibbonFooterControl](xref:@ActiproUIRoot.Controls.Bars.RibbonFooterControl).`Padding` to `0`. Any changes to padding should be assigned to [InfoBar](xref:@ActiproUIRoot.Controls.InfoBar).`Padding`. +Since the @if (avalonia) { [InfoBar](../../fundamentals/controls/info-bar.md) }@if (wpf) { [InfoBar](../../shared/windows-controls/info-bar.md) } should fill the entire area of the footer, it is important to set the [RibbonFooterControl](xref:@ActiproUIRoot.Controls.Bars.RibbonFooterControl).`Padding` to `0`. Any changes to padding should be assigned to [InfoBar](xref:@ActiproUIRoot.Controls.InfoBar).`Padding`. ### Background Color -The default background color for [InfoBar](../../shared/windows-controls/info-bar.md) (at the default [InfoBarSeverity](xref:@ActiproUIRoot.Controls.InfoBarSeverity)) is different than the default footer background color. It is recommended to apply a `Style` to [InfoBar](xref:@ActiproUIRoot.Controls.InfoBar) that changes the `Background` property to `Transparent` when the default [InfoBarSeverity](xref:@ActiproUIRoot.Controls.InfoBarSeverity) is used as this will allow the footer's own `Background` to be shown. +The default background color for @if (avalonia) { [InfoBar](../../fundamentals/controls/info-bar.md) }@if (wpf) { [InfoBar](../../shared/windows-controls/info-bar.md) } (at the default [InfoBarSeverity](xref:@ActiproUIRoot.Controls.InfoBarSeverity)) is different than the default footer background color. It is recommended to apply a `Style` to [InfoBar](xref:@ActiproUIRoot.Controls.InfoBar) that changes the `Background` property to `Transparent` when the default [InfoBarSeverity](xref:@ActiproUIRoot.Controls.InfoBarSeverity) is used as this will allow the footer's own `Background` to be shown. > [!IMPORTANT] > Setting the `Background` property directly will prevent the background color from changing to match the current [InfoBarSeverity](xref:@ActiproUIRoot.Controls.InfoBarSeverity). @@ -107,8 +127,54 @@ The easiest solution is to bind the [InfoBar](xref:@ActiproUIRoot.Controls.InfoB ### Example -The following example fully demonstrates one way to use an [InfoBar](../../shared/windows-controls/info-bar.md) on a footer: +The following example fully demonstrates one way to use an @if (avalonia) { [InfoBar](../../fundamentals/controls/info-bar.md) }@if (wpf) { [InfoBar](../../shared/windows-controls/info-bar.md) } on a footer: + +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + + + + + + + + + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared" @@ -145,4 +211,8 @@ xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared" -``` \ No newline at end of file +``` +} + +> [!TIP] +> See the "Footer" Bars Ribbon QuickStart of the Sample Browser application for a full demonstration of working with the ribbon footer. \ No newline at end of file diff --git a/Documentation/topics/bars/ribbon-features/index.md b/Documentation/topics/bars/ribbon-features/index.md index 1c74776b..856a0618 100644 --- a/Documentation/topics/bars/ribbon-features/index.md +++ b/Documentation/topics/bars/ribbon-features/index.md @@ -45,14 +45,20 @@ See the [Resizing and Variants](resizing.md) topic for more information. ## Application Button -Ribbon supports an application button that can open a menu that is generally populated by application-wide options such as **New**, **Open**, and **Save** operations. +@if (avalonia) { +Ribbon supports an application button that can open a [backstage](backstage.md) when the button is clicked. +} +@if (wpf) { +Ribbon supports an application button that can open a menu that is generally populated by application-wide options such as **New**, **Open**, and **Save**. Either a traditional application menu or more modern backstage can be displayed when the button is clicked. See the respective topics for more details on configuring each style. +} The application button can also be hidden if a corresponding menu is not necessary or desired. See the [Application Button](application-button.md) topic for more information. +@if (wpf) { ## Application Menu The application menu is a medium-sized popup that can be displayed when clicking the application button and is generally populated by application-wide menu items such as file operations or printing. @@ -62,6 +68,7 @@ A section at the bottom of the application menu is optional and can be used for Any content can optionally be placed on the far side of the application menu as well. A list of recent documents is commonly displayed there. See the [Application Menu](application-menu.md) topic for more information. +} ## Backstage @@ -129,7 +136,12 @@ See the [Options Button](options-button.md) topic for more information. ## Recent Documents +@if (avalonia) { +A recent document control is intended to be used within a backstage. +} +@if (wpf) { A recent document control is intended to be used within a backstage or an application menu. +} Recently opened documents are listed in a sorted order and can be clicked to open them. Hovering the mouse over a document provides its full path. diff --git a/Documentation/topics/bars/ribbon-features/key-tips.md b/Documentation/topics/bars/ribbon-features/key-tips.md index 10af8ab8..cfd5ea39 100644 --- a/Documentation/topics/bars/ribbon-features/key-tips.md +++ b/Documentation/topics/bars/ribbon-features/key-tips.md @@ -46,11 +46,20 @@ All Bars controls have a `KeyTipText` property (such as [BarButton](xref:@Actipr This code sample shows how to assign key tip text for a [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton). +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ## KeyTipService @@ -65,6 +74,7 @@ It has these important properties: | [KeyTipOpeningEvent](xref:@ActiproUIRoot.Controls.Bars.KeyTipService.KeyTipOpeningEvent) Routed Event | Gets the event that is raised when a key tip is opening. The [KeyTipOpeningEventArgs](xref:@ActiproUIRoot.Controls.Bars.KeyTipOpeningEventArgs) data can be used to position key tips differently than the default location. | | [KeyTipTextProperty](xref:@ActiproUIRoot.Controls.Bars.KeyTipService.KeyTipTextProperty) Attached Property | Gets or sets the key tip text for the element to which it is applied. All Bars controls that support key tips wrap this attached property with a `KeyTipText` property. | +@if (wpf) { > [!WARNING] > The Bars [KeyTipService](xref:@ActiproUIRoot.Controls.Bars.KeyTipService) class name is ambiguous with Microsoft Ribbon's `Sytem.Windows.Controls.KeyTipService` class and may require using a fully-qualified domain name to resolve the ambiguity. In XAML, you must use a namespace prefix as shown below: > ```xaml @@ -72,6 +82,7 @@ It has these important properties: > ... > > ``` +} ### Key Tip Mode Shortcuts diff --git a/Documentation/topics/bars/ribbon-features/layout-and-density.md b/Documentation/topics/bars/ribbon-features/layout-and-density.md index e2cbc47c..e080cdd4 100644 --- a/Documentation/topics/bars/ribbon-features/layout-and-density.md +++ b/Documentation/topics/bars/ribbon-features/layout-and-density.md @@ -29,18 +29,25 @@ The `Classic` layout mode, first introduced with Office 2007, uses a taller ribb The `Simplified` layout mode is a modern refinement of the ribbon that appears more like a traditional toolbar with a single row of controls but can still dynamically adjust to fill the available space. When necessary, controls that do not have room to appear on the primary ribbon are moved to an overflow menu. +@if (wpf) { > [!NOTE] > It is recommended that when using the `Simplified` layout mode, set the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.Ribbon.UserInterfaceDensity) property to `Spacious`, which is more touch-friendly than the `Compact` default. The `Spacious` density will also use medium size images when available in place of small size images. +} > [!TIP] > See the "Layout Modes" Bars Ribbon QuickStart of the Sample Browser application for a demonstration of layout modes and user options. ## User Interface Density +@if (avalonia) { +Actipro Ribbon works with [Actipro Themes](../../themes/index.md) to support multiple levels of density that adjust the padding of user interface elements. See the [User Interface Density](../../themes/user-interface-density.md) topic of Actipro Themes for more information. +} +@if (wpf) { Actipro Ribbon supports multiple levels of density that adjust the padding of user interface elements. Set the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.Ribbon.UserInterfaceDensity) property to one of the following [UserInterfaceDensity](xref:@ActiproUIRoot.Themes.UserInterfaceDensity) values. - `Compact` is the default and is best for traditional mouse interactions such as when using [RibbonLayoutMode](xref:@ActiproUIRoot.Controls.Bars.RibbonLayoutMode).[Classic](xref:@ActiproUIRoot.Controls.Bars.RibbonLayoutMode.Classic). - `Spacious` is great for touch interactions and should generally be set for [RibbonLayoutMode](xref:@ActiproUIRoot.Controls.Bars.RibbonLayoutMode).[Simplified](xref:@ActiproUIRoot.Controls.Bars.RibbonLayoutMode.Simplified). - `Normal` is a little in-between `Compact` and `Spacious` for a more balanced approach. > [!TIP] -> See the "User Interface Density" Bars Ribbon QuickStart of the Sample Browser application for a demonstration of different density values applied to classic and simplified ribbons. \ No newline at end of file +> See the "User Interface Density" Bars Ribbon QuickStart of the Sample Browser application for a demonstration of different density values applied to classic and simplified ribbons. +} \ No newline at end of file diff --git a/Documentation/topics/bars/ribbon-features/options-button.md b/Documentation/topics/bars/ribbon-features/options-button.md index a435bfac..99ca4839 100644 --- a/Documentation/topics/bars/ribbon-features/options-button.md +++ b/Documentation/topics/bars/ribbon-features/options-button.md @@ -81,8 +81,15 @@ The menu item labels for each option are defined by the following string resourc The following example demonstrates how to change the `"Always Show Ribbon"` menu item label to `"Show Full Ribbon"`: +@if (avalonia) { +```csharp +ActiproSoftware.Properties.Bars.SR.SetCustomString(ActiproSoftware.Properties.Bars.SRName.UIRibbonMenuItemAlwaysShowRibbonText, "Show Full Ribbon"); +``` +} +@if (wpf) { ```csharp ActiproSoftware.Products.Bars.SR.SetCustomString(ActiproSoftware.Products.Bars.SRName.UIRibbonMenuItemAlwaysShowRibbonText.ToString(), "Show Full Ribbon"); ``` +} See the [Customizing String Resources](../../customizing-string-resources.md) topic for additional details. \ No newline at end of file diff --git a/Documentation/topics/bars/ribbon-features/quick-access-toolbar.md b/Documentation/topics/bars/ribbon-features/quick-access-toolbar.md index 194068e1..bcc45003 100644 --- a/Documentation/topics/bars/ribbon-features/quick-access-toolbar.md +++ b/Documentation/topics/bars/ribbon-features/quick-access-toolbar.md @@ -27,6 +27,38 @@ To make it easy for users to add or remove common items from the toolbar, additi This code sample shows how to define the quick access toolbar items for a ribbon. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + + + + + + + + + + + + + ... + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -56,6 +88,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ``` +} ## MVVM Support @@ -66,9 +99,16 @@ The optional companion [MVVM Library](../mvvm-support.md) defines a [RibbonQuick > [!TIP] > See the [MVVM Support](../mvvm-support.md) topic for more information on how to use the library's view models and view templates to create and manage your application's bars controls with MVVM techniques. +@if (avalonia) { +## Customizing the Toolbar Theme + +The [RibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBar) instance can be customized by setting a `ControlTheme` to the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[QuickAccessToolBarTheme](xref:@ActiproUIRoot.Controls.Bars.Ribbon.QuickAccessToolBarTheme) property. This `ControlTheme` is applied to the control when it is added to the ribbon. +} +@if (wpf) { ## Customizing the Toolbar Style The [RibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBar) instance can be customized by setting a `Style` to the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[QuickAccessToolBarStyle](xref:@ActiproUIRoot.Controls.Bars.Ribbon.QuickAccessToolBarStyle) property. This `Style` is applied to the control when it is added to the ribbon. +} ## Quick Access Toolbar Mode @@ -113,6 +153,7 @@ Ribbon includes a very flexible framework for supporting multiple forms of end-u See the [Serialization](serialization.md) topic for details on how to persist the state of the quick access toolbar to be restored later. +@if (wpf) { ## Monochrome Images Several Actipro themes require the use of white monochrome images in specific portions of the ribbon user interface. Ribbon has special logic that will automatically convert `BitmapSource` and `DrawingImage` images to a pure white monochrome equivalent for proper display in these scenarios. This allows you to use a single image set for your entire UI while still supporting modern UI. @@ -141,6 +182,7 @@ In some cases, such as for a vector icon that has a portion showing a selected c This can be achieved by setting the attached [ImageProvider](xref:@ActiproUIRoot.Media.ImageProvider).`CanAdapt` property to `false` on the portion for the selected color. That will tell the converter to skip over converting colors within that portion of the image. See the [Image Provider](../../themes/image-provider.md) topic for more details on working with image adaptation. +} ## Key Tips diff --git a/Documentation/topics/bars/ribbon-features/recent-documents.md b/Documentation/topics/bars/ribbon-features/recent-documents.md index a23687db..4b02c373 100644 --- a/Documentation/topics/bars/ribbon-features/recent-documents.md +++ b/Documentation/topics/bars/ribbon-features/recent-documents.md @@ -5,11 +5,20 @@ order: 70 --- # Recent Documents +@if (avalonia) { +A [RecentDocumentControl](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl) is a control that is intended to be used within a [backstage](backstage.md). + +![Screenshot](../images/recent-documents.png) + +*A RecentDocumentControl shown in a backstage* +} +@if (wpf) { A [RecentDocumentControl](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl) is a control that is intended to be used within a [backstage](backstage.md) or as the [RibbonApplicationButton](xref:@ActiproUIRoot.Controls.Bars.RibbonApplicationButton).[MenuAdditionalContent](xref:@ActiproUIRoot.Controls.Bars.RibbonApplicationButton.MenuAdditionalContent) of an [application menu](application-menu.md). ![Screenshot](../images/recent-documents.png) *A RecentDocumentControl shown in a backstage and application menu* +} Recently opened documents are listed in a sorted order and can be clicked to open them. Hovering the mouse over a document provides its full path. @@ -17,10 +26,11 @@ Clicking on a document's **Pin** button will toggle the pinned state of the docu ## Adding to a Backstage -The `RecentDocumentControl` can be added to a [Backstage](application-menu.md) as content for a [RibbonBackstageTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageTabItem). +The `RecentDocumentControl` can be added to a [Backstage](backstage.md) as content for a [RibbonBackstageTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageTabItem). When a `RecentDocumentControl` is included in a [RibbonBackstageTabItem](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstageTabItem), it is recommended to leave the [RecentDocumentControl](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl).[UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl.UseLargeSize) property at the default value of `true`. This will enable the control to take advantage of the additional space afforded on a backstage and render similar to Office with large icons and descriptions. +@if (wpf) { ## Adding to an Application Menu The `RecentDocumentControl` can be added to the [RibbonApplicationButton](xref:@ActiproUIRoot.Controls.Bars.RibbonApplicationButton).[MenuAdditionalContent](xref:@ActiproUIRoot.Controls.Bars.RibbonApplicationButton.MenuAdditionalContent) property for use on an application menu. @@ -29,27 +39,46 @@ The `RecentDocumentControl` can be added to the [RibbonApplicationButton](xref:@ > When used on an application menu, set the [RecentDocumentControl](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl).[UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl.UseLargeSize) property to `false` so the control can render properly in a smaller size. See the [Application Menu](application-menu.md) topic for more details on defining `MenuAdditionalContent` including sample code for using a `RecentDocumentControl`. +} ## Managing the Recent Document List +@if (avalonia) { +The recent document list is managed by adding instances of [RecentDocumentItem](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentItem) to the [RecentDocumentControl](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl).`Items` property or setting [RecentDocumentControl](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl).`ItemsSource` to an enumerable of [RecentDocumentItem](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentItem) instances. + +> [!CAUTION] +> Only instances of [RecentDocumentItem](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentItem) should be added to the `Items` or `ItemsSource` properties. Otherwise, exceptions can be thrown while attempting to process the items. +> +> See the "Recent Documents" Bars Ribbon QuickStart of the Sample Browser application for an example of adapting a collection of view models to a collection of [RecentDocumentItem](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentItem). + +The following key properties are available for [RecentDocumentItem](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentItem): + +|Property Name|Description| +|-----|-----| +| [ImageSourceLarge](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentItem.ImageSourceLarge) | An `IImage` that is displayed for the document when [RecentDocumentControl](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl).[UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl.UseLargeSize) is `true`. | +| [ImageSourceSmall](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentItem.ImageSourceSmall) | An `IImage` that is displayed for the document when [RecentDocumentControl](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl).[UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl.UseLargeSize) is `false`. | +| [IsPinned](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentItem.IsPinned) | Indicates if the document is pinned to the top of the list. | +| [LastOpenedDateTime](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentItem.LastOpenedDateTime) | The date and time when the document was last opened. Documents are sorted so the most recently opened documents appear at the top. | +| [Location](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentItem.Location) | A `Uri` indicating the location of the document. | + +} +@if (wpf) { The recent document list is managed by the [RecentDocumentManager](xref:@ActiproUIRoot.DocumentManagement.RecentDocumentManager) that is assigned to the [RecentDocumentControl](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl).[Manager](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl.Manager) property. This object maintains a list of [IDocumentReference](xref:@ActiproUIRoot.DocumentManagement.IDocumentReference) objects. See the [Document Management](../../shared/windows-document-management.md) topic for details on how to manage the list using the [RecentDocumentManager](xref:@ActiproUIRoot.DocumentManagement.RecentDocumentManager), including the ability to limit the number of documents shown, associate icons with files, and set descriptions. Changes to the [RecentDocumentManager](xref:@ActiproUIRoot.DocumentManagement.RecentDocumentManager) should automatically update the `RecentDocumentControl`. However, certain changes such as updating a document reference's last-opened date/time may not be picked up by the manager as a change. In these cases you must call [RecentDocumentManager](xref:@ActiproUIRoot.DocumentManagement.RecentDocumentManager).[RebindFilteredDocuments](xref:@ActiproUIRoot.DocumentManagement.RecentDocumentManager.RebindFilteredDocuments*) explicitly and the `RecentDocumentControl` will update in response. +} ## Processing Document Clicks -When the end user clicks on a document listed in the `RecentDocumentControl`, the [RecentDocumentControl](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl).[OpenCommand](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl.OpenCommand) will be executed with the corresponding [IDocumentReference](xref:@ActiproUIRoot.DocumentManagement.IDocumentReference) passed as the command parameter. Since this action indicates the document should be opened, the `OpenCommand` property defaults to the standard WPF `ApplicationCommands.Open` routed command, but any command can be assigned to replace the default. +When the end user clicks on a document listed in the `RecentDocumentControl`, the [RecentDocumentControl](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl).[OpenCommand](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl.OpenCommand) will be executed with the corresponding @if (avalonia) { [RecentDocumentItem](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentItem) }@if (wpf) { [IDocumentReference](xref:@ActiproUIRoot.DocumentManagement.IDocumentReference) } passed as the command parameter. @if (wpf) { Since this action indicates the document should be opened, the `OpenCommand` property defaults to the standard WPF `ApplicationCommands.Open` routed command, but any command can be assigned to replace the default. } -In the code that handles the execution of the command, use the command parameter (which is an [IDocumentReference](xref:@ActiproUIRoot.DocumentManagement.IDocumentReference)) to determine which document to open. Since `ApplicationCommands.Open` might be raised in scenarios unrelated to opening a recent document, it is generally safe to assume that if no command parameter is passed, the command was not raised by the `RecentDocumentControl` and the default action for the command (e.g., browse for a file with an **Open File** dialog) should be invoked. - -> [!TIP] -> See the "Recent Documents" Bars Ribbon QuickStart of the Sample Browser application for a full demonstration of configuring a backstage or application menu with a `RecentDocumentControl` and working with a `RecentDocumentManager`. +In the code that handles the execution of the command, use the command parameter @if (avalonia) { (which is a [RecentDocumentItem](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentItem)) }@if (wpf) { (which is an [IDocumentReference](xref:@ActiproUIRoot.DocumentManagement.IDocumentReference)) } to determine which document to open. Since @if (avalonia) { the associated [RecentDocumentControl](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl).[OpenCommand](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl.OpenCommand) }@if (wpf) { `ApplicationCommands.Open` } might be raised in scenarios unrelated to opening a recent document, it is generally safe to assume that if no command parameter is passed, the command was not raised by the `RecentDocumentControl` and the default action for the command (e.g., browse for a file with an **Open File** dialog) should be invoked. ## Grouping -The `RecentDocumentControl` supports grouping documents based on [IDocumentReference](xref:@ActiproUIRoot.DocumentManagement.IDocumentReference).[LastOpenedDateTime](xref:@ActiproUIRoot.DocumentManagement.IDocumentReference.LastOpenedDateTime). Set the [AllowGrouping](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl.AllowGrouping) property to `false` to disable this functionality (defaults to `true`). +The `RecentDocumentControl` supports grouping documents based on @if (avalonia) { [RecentDocumentItem](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentItem).[LastOpenedDateTime](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentItem.LastOpenedDateTime) }@if (wpf) { [IDocumentReference](xref:@ActiproUIRoot.DocumentManagement.IDocumentReference).[LastOpenedDateTime](xref:@ActiproUIRoot.DocumentManagement.IDocumentReference.LastOpenedDateTime) }. Set the [AllowGrouping](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl.AllowGrouping) property to `false` to disable this functionality (defaults to `true`). When grouping is allowed, all pinned documents will appear at the top. Unpinned documents will be grouped based on how recently they were last accessed. Each group label is defined by a localizable `String` resource value. The following groups are available: @@ -75,4 +104,13 @@ Each of these properties are initialized to a localizable `String` resource valu | `UIRecentDocumentControlNameColumnText` | The text displayed for [NameColumnText](xref:@ActiproUIRoot.Controls.Bars.RecentDocumentControl.NameColumnText). The default value is `"Name"`. | -See the [Customizing String Resources](../../customizing-string-resources.md) topic for additional details on working with string resources. \ No newline at end of file +See the [Customizing String Resources](../../customizing-string-resources.md) topic for additional details on working with string resources. + +@if (avalonia) { +> [!TIP] +> See the "Recent Documents" Bars Ribbon QuickStart of the Sample Browser application for a full demonstration of configuring a backstage with a `RecentDocumentControl` and working with view models. +} +@if (wpf) { +> [!TIP] +> See the "Recent Documents" Bars Ribbon QuickStart of the Sample Browser application for a full demonstration of configuring a backstage or application menu with a `RecentDocumentControl` and working with a `RecentDocumentManager`. +} \ No newline at end of file diff --git a/Documentation/topics/bars/ribbon-features/resizing.md b/Documentation/topics/bars/ribbon-features/resizing.md index 64281f38..2fcfcfc7 100644 --- a/Documentation/topics/bars/ribbon-features/resizing.md +++ b/Documentation/topics/bars/ribbon-features/resizing.md @@ -31,11 +31,20 @@ See the "Explicit Variant Sizing" section below for more details on controlling An individual group on the ribbon can be configured to define its own **Group Overflow** button instead of using the default **Tab Overflow** button. To enable this functionality, set [RibbonGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonGroup).[ChildOverflowTarget](xref:@ActiproUIRoot.Controls.Bars.RibbonGroup.ChildOverflowTarget) = [RibbonGroupChildOverflowTarget](xref:@ActiproUIRoot.Controls.Bars.RibbonGroupChildOverflowTarget).[Group](xref:@ActiproUIRoot.Controls.Bars.RibbonGroupChildOverflowTarget.Group) as shown in the following example: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} When enabled and controls in a group need to overflow, a **Group Overflow** button will appear as the last item in the group. Overflowed controls will appear in the popup menu just like they appear in the **Tab Overflow** menu except there is no need to display the group's label as a header. @@ -72,6 +81,25 @@ Most controls define a `ToolBarItemCollapseBehavior` property (e.g., [BarButton] The following example shows buttons using the `ToolBarItemVariantBehavior` and `ToolBarItemCollapseBehavior` properties in a ribbon using `Simplified` layout mode: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -88,6 +116,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ``` +} ## Classic Layout Strategy @@ -123,6 +152,22 @@ By default, a control group will attempt all variant sizes from `Large` to `Smal The following example defines three buttons that will always appear in a single vertical stack because they are defined in a control group that does not support the `Large` variant size. Labels will be visible when the control group is `Medium`, and only icons will display when the control group is `Small`. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + ... + +... +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -136,6 +181,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ### Multi-Row Control Groups @@ -148,9 +194,46 @@ When using multi-row layouts, a [RibbonControlGroup](xref:@ActiproUIRoot.Control *The same multi-row control group using two rows compared to three rows* +@if (avalonia) { +When arranged in two rows, control groups are sorted in the order they are defined. In three-row mode, the default behavior will sort groups so each row is as narrow as possible. When desired, the [RibbonMultiRowControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonMultiRowControlGroup).[ThreeRowItemSortOrder](xref:@ActiproUIRoot.Controls.Bars.RibbonMultiRowControlGroup.ThreeRowItemSortOrder) property is used to set an explicit sort order where the zero-based index of each control group is defined by a `List` in the preferred sort order. The following example demonstrates defining a three-row sort order. +} +@if (wpf) { When arranged in two rows, control groups are sorted in the order they are defined. In three-row mode, the default behavior will sort groups so each row is as narrow as possible. When desired, the [RibbonMultiRowControlGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonMultiRowControlGroup).[ThreeRowItemSortOrder](xref:@ActiproUIRoot.Controls.Bars.RibbonMultiRowControlGroup.ThreeRowItemSortOrder) property is used to set an explicit sort order where the zero-based index of each control group is listed in the preferred sort order, separated by spaces (e.g., `"0 1 3 4 2"`). The following example demonstrates defining a three-row sort order. +} +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +xmlns:generic="using:System.Collections.Generic" +... + + + + + 0 + 1 + 3 + 4 + 2 + + + + ... + ... + + + ... + + ... + ... + ... + + +... +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -171,6 +254,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ### Separators @@ -192,6 +276,22 @@ By default, separators are not displayed between neighboring control groups in a The following example defines four buttons, where the last three are part of a control group. The control group is configured to only show a separator when the group of three buttons is the same variant size as the first button (which, since it is not in a control group, will always be `Large`). A separator will not be displayed if the control group is a `Medium` or `Small` variant size. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -205,6 +305,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} #### Multi-Row Layout Separators @@ -254,6 +355,84 @@ Normally, items are overflowed one-by-one starting at the far side of the ribbon > [!NOTE] > In the Simplified layout mode, [VariantSize](xref:@ActiproUIRoot.Controls.Bars.VariantSize).[Collapsed](xref:@ActiproUIRoot.Controls.Bars.VariantSize.Collapsed) indicates a control should appear on the appropriate **Overflow Menu**. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +... +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -329,6 +508,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ### Applying to Classic Layout Mode @@ -353,6 +533,61 @@ Normally, group sizes are reduced from `Large` to `Small` before collapsing and a. `GroupE` moves from `Small` to `Collapsed`. a. `GroupD` moves from `Small` to `Collapsed`. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + ... + ... + ... + ... + ... + + +... +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -405,12 +640,13 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ### Implicit Sizing Fallback The [VariantCollection](xref:@ActiproUIRoot.Controls.Bars.VariantCollection) does not have to define sizing for all items. Any item whose key *is not* explicitly defined by at least one [SizeVariant](xref:@ActiproUIRoot.Controls.Bars.SizeVariant).[TargetKey](xref:@ActiproUIRoot.Controls.Bars.SizeVariant.TargetKey) entry will implicitly reduce in size using the default logic (e.g., `Large` to `Medium` to `Small` before collapsing/overflowing). -Any item that *is* explicitly defined by at least one [SizeVariant](xref:@ActiproUIRoot.Controls.Bars.SizeVariant).[TargetKey](xref:@ActiproUIRoot.Controls.Bars.SizeVariant.TargetKey) entry will still implicitly collapse as the next stage (skipping all other variant sizes) even if a `Collapsed` variant size was not explicitly set. In the `Classic` layout mode only, this implicit auto-collapse behavior can be preventing by setting [RibbonGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonGroup).[CanAutoCollapse](xref:@ActiproUIRoot.Controls.Bars.RibbonGroup.CanAutoCollapse) = `false`. +Any item that *is* explicitly defined by at least one [SizeVariant](xref:@ActiproUIRoot.Controls.Bars.SizeVariant).[TargetKey](xref:@ActiproUIRoot.Controls.Bars.SizeVariant.TargetKey) entry will still implicitly collapse as the next stage (skipping all other variant sizes) even if a `Collapsed` variant size was not explicitly set. In the `Classic` layout mode only, this implicit auto-collapse behavior can be prevented by setting [RibbonGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonGroup).[CanAutoCollapse](xref:@ActiproUIRoot.Controls.Bars.RibbonGroup.CanAutoCollapse) = `false`. ## RibbonGallery diff --git a/Documentation/topics/bars/ribbon-features/screen-tips.md b/Documentation/topics/bars/ribbon-features/screen-tips.md index 858db876..9d40f45f 100644 --- a/Documentation/topics/bars/ribbon-features/screen-tips.md +++ b/Documentation/topics/bars/ribbon-features/screen-tips.md @@ -15,26 +15,26 @@ Since the [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip) class derives ## Screen Tip Infrastructure -For Bars controls that do not explicitly assign the `ToolTip` property to an instance of a `ToolTip` control (or a control that derives from `ToolTip`, like [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip)), a [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip) will be coerced based on the available data. +For Bars controls that do not explicitly assign the @if (avalonia) { `ToolTip.Tip` }@if (wpf) { `ToolTip` } property to an instance of a `ToolTip` control (or a control that derives from `ToolTip`, like [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip)), a [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip) will be coerced based on the available data. A [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip) is composed of three areas: [Header](xref:@ActiproUIRoot.Controls.Bars.ScreenTip.Header), `Content`, and [Footer](xref:@ActiproUIRoot.Controls.Bars.ScreenTip.Footer). ### Screen Tip Header -The base `Header` content is defined by the control's `ScreenTipHeader` property (e.g., [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[ScreenTipHeader](xref:@ActiproUIRoot.Controls.Bars.BarButton.ScreenTipHeader)). Most controls are configured with a default style that binds the `ScreenTipHeader` property to a `Title` property (e.g., [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[Title](xref:@ActiproUIRoot.Controls.Bars.BarButton.Title)) on the same control. +The base `Header` content is defined by the control's `ScreenTipHeader` property (e.g., [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[ScreenTipHeader](xref:@ActiproUIRoot.Controls.Bars.BarButton.ScreenTipHeader)). Most controls are configured with a default @if (avalonia) { theme }@if (wpf) { style } that binds the `ScreenTipHeader` property to a `Title` property (e.g., [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[Title](xref:@ActiproUIRoot.Controls.Bars.BarButton.Title)) on the same control. The screen tip `Header` can be set to any object supported by `ContentPresenter`. If the `ScreenTipHeader` property is undefined, the control's `Label` property (e.g., [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[Label](xref:@ActiproUIRoot.Controls.Bars.BarButton.Label)) will be converted to the base `Header` content. Any `Label` value that ends with ellipses (e.g., `"Print..."`) will trim the trailing ellipsis from the base `Header` content. -Finally, if the base `Header` content is a `string` and the control defines an `InputGestureText` property (e.g., [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[InputGestureText](xref:@ActiproUIRoot.Controls.Bars.BarButton.InputGestureText)), that gesture text will optionally be appended within parenthesis to the end of the `Header` content (e.g., `"Copy (Ctrl+C)"`). Appending the gesture text can be disabled by setting the `IsInputGestureTextVisible` property (e.g., [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[IsInputGestureTextVisible](xref:@ActiproUIRoot.Controls.Bars.BarButton.IsInputGestureTextVisible)) to `false`. +Finally, if the base `Header` content is a `string` and the control defines an @if (avalonia) { `InputGesture` property (e.g., [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[InputGesture](xref:@ActiproUIRoot.Controls.Bars.BarButton.InputGesture)) }@if (wpf) { `InputGestureText` property (e.g., [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[InputGestureText](xref:@ActiproUIRoot.Controls.Bars.BarButton.InputGestureText)) }, that gesture text will optionally be appended within parenthesis to the end of the `Header` content (e.g., `"Copy (Ctrl+C)"`). Appending the gesture text can be disabled by setting the `IsInputGestureTextVisible` property (e.g., [BarButton](xref:@ActiproUIRoot.Controls.Bars.BarButton).[IsInputGestureTextVisible](xref:@ActiproUIRoot.Controls.Bars.BarButton.IsInputGestureTextVisible)) to `false`. > [!NOTE] > If only the `Header` is defined for a screen tip (no other `Content` or `Footer`) then the screen tip will appear like a normal `ToolTip`. ### Screen Tip Content -The body of a control's `ToolTip` property defines the `Content` of a screen tip *unless* the property is set to a `ToolTip` control (or a control that derives from `ToolTip`, like [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip)). +The body of a control's @if (avalonia) { `ToolTip.Tip` }@if (wpf) { `ToolTip` } property defines the `Content` of a screen tip *unless* the property is set to a `ToolTip` control (or a control that derives from `ToolTip`, like [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip)). The screen tip `Content` can be set to any object supported by `ContentPresenter` and enables the display of complex layouts within a screen tip. @@ -46,8 +46,24 @@ The screen tip `Footer` can be set to any object supported by `ContentPresenter` ## Common Examples -Most Bars controls that do not explicitly assign the `ToolTip` property a value will display a basic screen tip with text automatically generated from the control's `Title` or `Label` with optional `InputGestureText`. The following are examples with the resulting screen tip defined by the comment above each sample: +Most Bars controls that do not explicitly assign the @if (avalonia) { `ToolTip.Tip` }@if (wpf) { `ToolTip` } property a value will display a basic screen tip with text automatically generated from the control's `Title` or `Label` with optional @if (avalonia) { `InputGesture` }@if (wpf) { `InputGestureText` }. The following are examples with the resulting screen tip defined by the comment above each sample: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -61,19 +77,51 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ``` +} -By setting the `ToolTip` property to a string value, the basic screen tip like that from the previous example will display an additional description for the content. The following example would display a screen tip with the header `"Copy to Clipboard (Ctrl+C)"` and text content of `"Copies the selection to the clipboard"`. +By setting the @if (avalonia) { `ToolTip.Tip` }@if (wpf) { `ToolTip` } property to a string value, the basic screen tip like that from the previous example will display an additional description for the content. The following example would display a screen tip with the header `"Copy to Clipboard (Ctrl+C)"` and text content of `"Copies the selection to the clipboard"`. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} ## Explicitly Defining a Screen Tip Since a [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip) derives from a standard `ToolTip`, you can define it like a standard `ToolTip` as well. The following example shows explicitly defining a [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip): +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + + + + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -93,11 +141,26 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ``` +} ## Use Screen Tip Anywhere Yes, [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip) can really be used on any control! The following example shows a standard `TextBox` control configured with a `ScreenTip`: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + Screen tips can be used with any control to enhance the user experience. + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -109,6 +172,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ``` +} ## ScreenTipService @@ -130,10 +194,12 @@ Most of the screen tip content properties are of type object, allowing you to pa Screen tip content can be dynamically generated. This allows you to modify the screen tip data on demand to best reflect the current state of the control. -To do this, listen to the [ScreenTipService](xref:@ActiproUIRoot.Controls.Bars.ScreenTipService).[ScreenTipOpening](xref:@ActiproUIRoot.Controls.Bars.ScreenTipService.ScreenTipOpening) event available as `ScreenTipService.Current.ScreenToOpening`. That event is raised before a screen tip is about to display for a Bars control. In the event handler, you may change the screen tip before it is rendered to the end user. +To do this, listen to the [ScreenTipService](xref:@ActiproUIRoot.Controls.Bars.ScreenTipService).[ScreenTipOpening](xref:@ActiproUIRoot.Controls.Bars.ScreenTipService.ScreenTipOpening) event available as `ScreenTipService.Current.ScreenTipOpening`. That event is raised before a screen tip is about to display for a control. In the event handler, you may change the screen tip before it is rendered to the end user. +@if (wpf) { > [!IMPORTANT] > By default, only Bars controls are configured to raise the `ScreenTipOpening` event. Custom controls that want to utilize the same event system should call [ScreenTipService](xref:@ActiproUIRoot.Controls.Bars.ScreenTipService).[NotifyToolTipOpening](xref:@ActiproUIRoot.Controls.Bars.ScreenTipService.NotifyToolTipOpening*) from their own `ToolTipOpening` event handler. +} ## Complex Content Width @@ -141,11 +207,19 @@ By default, screen tips are relatively narrow and work well for text-based conte When a [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip) is explicitly defined, this property can be set directly on the control. In other scenarios, listen to the [ScreenTipService](xref:@ActiproUIRoot.Controls.Bars.ScreenTipService).[ScreenTipOpening](xref:@ActiproUIRoot.Controls.Bars.ScreenTipService.ScreenTipOpening) event and alter the [ComplexContentWidth](xref:@ActiproUIRoot.Controls.Bars.ScreenTip.ComplexContentWidth) property before a screen tip is displayed. +@if (wpf) { ## Context-Sensitive Help Implementation The [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip).[Footer](xref:@ActiproUIRoot.Controls.Bars.ScreenTip.Footer) is a great place to prompt the user about context-sensitive help. For instance, an icon could be displayed along with a message to "Press F1 for more information". To handle this, simply process an `Execute` handler for the standard `ApplicationCommands.Help` command. Then in that code, check the [ScreenTipService](xref:@ActiproUIRoot.Controls.Bars.ScreenTipService).[CurrentScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTipService.CurrentScreenTip) property to see if there is a [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip) currently visible. If there is, show the appropriate topic in your help file. The [ScreenTip](xref:@ActiproUIRoot.Controls.Bars.ScreenTip).`Tag` property is a convenient location to store data related to context-sensitive help. +} +@if (avalonia) { +> [!TIP] +> See the "Screen Tips" Bars Ribbon QuickStart of the Sample Browser application for a full demonstration of multiple screen tip concepts and on-demand content. +} +@if (wpf) { > [!TIP] -> See the "Screen Tips" Bars Ribbon QuickStart of the Sample Browser application for a full demonstration of multiple screen tip concepts, on-demand content, and handling context-sensitive help. \ No newline at end of file +> See the "Screen Tips" Bars Ribbon QuickStart of the Sample Browser application for a full demonstration of multiple screen tip concepts, on-demand content, and handling context-sensitive help. +} \ No newline at end of file diff --git a/Documentation/topics/bars/ribbon-features/serialization.md b/Documentation/topics/bars/ribbon-features/serialization.md index 9116503b..0df43f6a 100644 --- a/Documentation/topics/bars/ribbon-features/serialization.md +++ b/Documentation/topics/bars/ribbon-features/serialization.md @@ -23,14 +23,27 @@ By default, the `Serialize` and `Deserialize` methods will include all supported [RibbonSerializerOptions](xref:@ActiproUIRoot.Controls.Bars.RibbonSerializerOptions) is an enumeration that allows multiple flags to be set that determine which options should be processed during the serialization/deserialization process. The following flags are available: +@if (avalonia) { | Flag | Description | | ---- | ---- | | [LayoutMode](xref:@ActiproUIRoot.Controls.Bars.RibbonSerializerOptions.LayoutMode) | Indicates if the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[LayoutMode](xref:@ActiproUIRoot.Controls.Bars.Ribbon.LayoutMode) property should be processed. | | [MinimizedState](xref:@ActiproUIRoot.Controls.Bars.RibbonSerializerOptions.MinimizedState) | Indicates if the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[IsMinimized](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsMinimized) property should be processed. | +| [QuickAccessToolBarAllowLabels](xref:@ActiproUIRoot.Controls.Bars.RibbonSerializerOptions.QuickAccessToolBarAllowLabels) | Indicates if the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[AllowLabelsOnQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.Ribbon.AllowLabelsOnQuickAccessToolBar) property should be processed. | +| [QuickAccessToolBarLocation](xref:@ActiproUIRoot.Controls.Bars.RibbonSerializerOptions.QuickAccessToolBarLocation) | Indicates if the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[QuickAccessToolBarLocation](xref:@ActiproUIRoot.Controls.Bars.Ribbon.QuickAccessToolBarLocation) property should be processed. | +| [QuickAccessToolBarMode](xref:@ActiproUIRoot.Controls.Bars.RibbonSerializerOptions.QuickAccessToolBarMode) | Indicates if the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[QuickAccessToolBarMode](xref:@ActiproUIRoot.Controls.Bars.Ribbon.QuickAccessToolBarMode) property should be processed. | +| [QuickAccessToolBarItems](xref:@ActiproUIRoot.Controls.Bars.RibbonSerializerOptions.QuickAccessToolBarItems) | Indicates if the ribbon's [RibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBar).`Items` collection should be processed. | +} +@if (wpf) { +| Flag | Description | +| ---- | ---- | +| [LayoutMode](xref:@ActiproUIRoot.Controls.Bars.RibbonSerializerOptions.LayoutMode) | Indicates if the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[LayoutMode](xref:@ActiproUIRoot.Controls.Bars.Ribbon.LayoutMode) property should be processed. | +| [MinimizedState](xref:@ActiproUIRoot.Controls.Bars.RibbonSerializerOptions.MinimizedState) | Indicates if the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[IsMinimized](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsMinimized) property should be processed. | +| [QuickAccessToolBarAllowLabels](xref:@ActiproUIRoot.Controls.Bars.RibbonSerializerOptions.QuickAccessToolBarAllowLabels) | Indicates if the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[AllowLabelsOnQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.Ribbon.AllowLabelsOnQuickAccessToolBar) property should be processed. | | [QuickAccessToolBarLocation](xref:@ActiproUIRoot.Controls.Bars.RibbonSerializerOptions.QuickAccessToolBarLocation) | Indicates if the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[QuickAccessToolBarLocation](xref:@ActiproUIRoot.Controls.Bars.Ribbon.QuickAccessToolBarLocation) property should be processed. | | [QuickAccessToolBarMode](xref:@ActiproUIRoot.Controls.Bars.RibbonSerializerOptions.QuickAccessToolBarMode) | Indicates if the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[QuickAccessToolBarMode](xref:@ActiproUIRoot.Controls.Bars.Ribbon.QuickAccessToolBarMode) property should be processed. | | [QuickAccessToolBarItems](xref:@ActiproUIRoot.Controls.Bars.RibbonSerializerOptions.QuickAccessToolBarItems) | Indicates if the ribbon's [RibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBar).`Items` collection should be processed. | | [UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.RibbonSerializerOptions.UserInterfaceDensity) | Indicates if the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.Ribbon.UserInterfaceDensity) property should be processed. | +} ## Restoring Quick Access Toolbar Items @@ -40,7 +53,8 @@ The [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[OnQuickAccessToolBarItem The [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) will first search any [RibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBar).[CommonItems](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBar.CommonItems) for a matching `Key`. If not found, the currently configured ribbon tabs and their content will be recursively searched, but not all controls can be found in this manner (like popup-based controls whose popup content is not loaded). -When an item of the desired `Key` cannot be automatically located, the [RibbonQuickAccessToolBarItemAddingEventArgs](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBarItemAddingEventArgs).[Item](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBarItemAddingEventArgs.Item) property must be manually assigned an appropriate item. If this property remains `null`, the `Key` will be ignored and nothing will be restored. +> [!WARNING] +> When an item of the desired `Key` cannot be automatically located, the [RibbonQuickAccessToolBarItemAddingEventArgs](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBarItemAddingEventArgs).[Item](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBarItemAddingEventArgs.Item) property must be manually assigned an appropriate item. If this property remains `null`, the `Key` will be ignored and nothing will be restored. > [!IMPORTANT] > If the [RibbonQuickAccessToolBar](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBar).`Items` collection is populated with view models, the item assigned to the [RibbonQuickAccessToolBarItemAddingEventArgs](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBarItemAddingEventArgs).[Item](xref:@ActiproUIRoot.Controls.Bars.RibbonQuickAccessToolBarItemAddingEventArgs.Item) property should also be a view model. Otherwise, if the `Items` collection is populated with controls, the `Item` should be a control. diff --git a/Documentation/topics/bars/ribbon-features/tab-row-toolbar.md b/Documentation/topics/bars/ribbon-features/tab-row-toolbar.md index 9f0b71c1..77feb9ac 100644 --- a/Documentation/topics/bars/ribbon-features/tab-row-toolbar.md +++ b/Documentation/topics/bars/ribbon-features/tab-row-toolbar.md @@ -5,7 +5,7 @@ order: 67 --- # Tab Row Toolbar -The ribbon's tab row toolbar is a control that can optionally be displayed on the far-right side of the ribbon, in the same row as the ribbon tabs. It generally shows common controls that are always available, such as `Sharing` or `Feedback` buttons. +The ribbon's tab row toolbar is a control that can optionally be displayed on the far side of the ribbon, in the same row as the ribbon tabs. It generally shows common controls that are always available, such as `Sharing` or `Feedback` buttons. ![Screenshot](../images/ribbon-tab-row-toolbar.png) @@ -22,6 +22,25 @@ The items to be displayed in the toolbar are assigned to the [RibbonTabRowToolBa This code sample shows how to define the tab row toolbar items for a ribbon. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + ... + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -38,6 +57,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ``` +} ## MVVM Support @@ -48,6 +68,18 @@ The optional companion [MVVM Library](../mvvm-support.md) defines a [RibbonTabRo > [!TIP] > See the [MVVM Support](../mvvm-support.md) topic for more information on how to use the library's view models and view templates to create and manage your application's bars controls with MVVM techniques. +@if (avalonia) { +## Customizing the Toolbar Theme + +The [RibbonTabRowToolBar](xref:@ActiproUIRoot.Controls.Bars.RibbonTabRowToolBar) instance can be customized by setting a `ControlTheme` to the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[TabRowToolBarTheme](xref:@ActiproUIRoot.Controls.Bars.Ribbon.TabRowToolBarTheme) property. This `ControlTheme` is applied to the control when it is added to the ribbon. +} +@if (wpf) { ## Customizing the Toolbar Style The [RibbonTabRowToolBar](xref:@ActiproUIRoot.Controls.Bars.RibbonTabRowToolBar) instance can be customized by setting a `Style` to the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[TabRowToolBarStyle](xref:@ActiproUIRoot.Controls.Bars.Ribbon.TabRowToolBarStyle) property. This `Style` is applied to the control when it is added to the ribbon. +} + +@if (avalonia) { +> [!TIP] +> See the "Tab Row Toolbar" Bars Ribbon QuickStart of the Sample Browser application for a full demonstration of working with tab row toolbar. +} \ No newline at end of file diff --git a/Documentation/topics/bars/ribbon-features/tabs-groups-controlgroups.md b/Documentation/topics/bars/ribbon-features/tabs-groups-controlgroups.md index 31c15659..3dbbb6d7 100644 --- a/Documentation/topics/bars/ribbon-features/tabs-groups-controlgroups.md +++ b/Documentation/topics/bars/ribbon-features/tabs-groups-controlgroups.md @@ -38,6 +38,29 @@ See the [Key Tips](../ribbon-features/key-tips.md) topic for more information on The following sample shows a ribbon with **Home** and **View** tabs defined using labels and key tips that are auto-generated from the defined key: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + + + + ... + + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -58,6 +81,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ``` +} See the "MVVM Support" section below for details on alternatively binding the items using MVVM techniques. @@ -80,7 +104,7 @@ See the [Contextual Tabs](contextual-tabs.md) topic for more details on that fea Some applications with only one ribbon tab may wish to hide the tab row entirely, so that a minimal ribbon is presented. This appearance can be achieved by setting these [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) properties: - [AreTabsVisible](xref:@ActiproUIRoot.Controls.Bars.Ribbon.AreTabsVisible) = `false` -- [ApplicationButton](xref:@ActiproUIRoot.Controls.Ribbon.Controls.Primitives.ApplicationButton) = `null` +- [IsApplicationButtonVisible](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsApplicationButtonVisible) = `false` - [TabRowToolBarContent](xref:@ActiproUIRoot.Controls.Bars.Ribbon.TabRowToolBarContent) = `null` ## Groups @@ -93,7 +117,7 @@ In the `Classic` layout mode, groups are prominently displayed in the UI with se See the [Resizing and Variants](resizing.md) topic for more details on how groups impact resizing and how to prevent a group from collapsing. -See the [Layout Modes and Density](layout-and-density.md) topic for more details on `Classic` modde. +See the [Layout Modes and Density](layout-and-density.md) topic for more details on `Classic` mode. ### Simplified Layout Mode @@ -101,7 +125,7 @@ In the `Simplified` layout mode, controls still visible in the ribbon will rende See the [Resizing and Variants](resizing.md) topic for more details on how groups impact resizing and how to configure a **Group Overflow** menu. -See the [Layout Modes and Density](layout-and-density.md) topic for more details on `Simplified` modde. +See the [Layout Modes and Density](layout-and-density.md) topic for more details on `Simplified` mode. ### Label @@ -147,6 +171,35 @@ Unlike other buttons, however, the [SmallImageSource](xref:@ActiproUIRoot.Contro The following XAML sample demonstrates how to define a [RibbonGroup](xref:@ActiproUIRoot.Controls.Bars.RibbonGroup) using labels and key tips that are auto-generated from the defined key: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + + + + ... + + + +... +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -173,6 +226,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} See the "MVVM Support" section below for details on alternatively binding the items using MVVM techniques. @@ -197,6 +251,32 @@ The primary purpose of a [RibbonControlGroup](xref:@ActiproUIRoot.Controls.Bars. The following XAML demonstrates how a control group might be used to achieve a result similar to Office's **Clipboard** group where the **Paste** control is always a large button and the related **Cut**, **Copy**, and **Format Painter** controls are stacked vertically in a group that never uses the [Large](xref:@ActiproUIRoot.Controls.Bars.VariantSize.Large) variant size: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + ... + + + + + + + + + + ... + + +... +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -220,6 +300,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} See the "MVVM Support" section below for details on alternatively binding the items using MVVM techniques. @@ -248,6 +329,47 @@ The primary purpose of a [RibbonMultiRowControlGroup](xref:@ActiproUIRoot.Contro The following XAML demonstrates how a multi-row control group might be used to display a set of controls that show in two or three rows, depending on available space: +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + +... +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -260,9 +382,9 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" + MenuResizeMode="Vertical" TextPath="Label" UseMenuItemAppearance="True" SelectedValuePath="Value" /> + MenuResizeMode="Vertical" TextPath="Label" UseMenuItemAppearance="True" SelectedValuePath="Value" /> @@ -286,6 +408,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} See the "MVVM Support" section below for details on alternatively binding the items using MVVM techniques. diff --git a/Documentation/topics/bars/toolbar-features/index.md b/Documentation/topics/bars/toolbar-features/index.md index ff8c8a50..c91995f1 100644 --- a/Documentation/topics/bars/toolbar-features/index.md +++ b/Documentation/topics/bars/toolbar-features/index.md @@ -17,6 +17,7 @@ The `StandaloneToolBar` control is meant to be a replacement for a native `ToolB See the [Standalone Toolbars](standalone-toolbars.md) topic for more information. +@if (wpf) { ## Mini-Toolbars The [MiniToolBar](xref:@ActiproUIRoot.Controls.Bars.MiniToolBar) control is intended for display in a popup, providing a compact set of controls that can alter the current selection or state of a target control. Any toolbar controls, including popup buttons with galleries, can be used on the mini-toolbar. @@ -26,3 +27,4 @@ The [MiniToolBar](xref:@ActiproUIRoot.Controls.Bars.MiniToolBar) control is inte *A context menu with a multi-row mini-toolbar* See the [Mini-Toolbars](mini-toolbars.md) topic for more information. +} \ No newline at end of file diff --git a/Documentation/topics/bars/toolbar-features/standalone-toolbars.md b/Documentation/topics/bars/toolbar-features/standalone-toolbars.md index 57076513..3d9d7d36 100644 --- a/Documentation/topics/bars/toolbar-features/standalone-toolbars.md +++ b/Documentation/topics/bars/toolbar-features/standalone-toolbars.md @@ -11,7 +11,7 @@ The [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar) con ### Main Toolbar -The [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar) control can be made to render similar to a ribbon in [Simplified layout mode](../ribbon-features/layout-and-density.md) where there is a single row of child controls. This appearance is great when the main window has system backdrop enabled and there is a single primary toolbar. +The [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar) control can be made to render similar to a ribbon in [Simplified layout mode](../ribbon-features/layout-and-density.md) where there is a single row of child controls. @if (wpf) { This appearance is great when the main window has system backdrop enabled and there is a single primary toolbar. } ![Screenshot](../images/standalone-toolbar.png) @@ -19,8 +19,24 @@ The [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar) con The main difference between the toolbar and a Simplified ribbon is in how overflow is achieved. The toolbar does not alter variant sizes of child controls and will overflow its items to a chevron popup when necessary. Whereas a Simplified ribbon can alter variant sizes of child controls when width is changed and overflows its items to popup menus when necessary. +@if (avalonia) { +The toolbar's `Background`, `BorderBrush`, `BorderThickness`, `CornerRadius`, [HasShadow](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar.HasShadow), `ItemSpacing`, and `Padding` properties can be set to achieve an appearance like above. +} +@if (wpf) { The toolbar's `Background`, `BorderBrush`, `BorderThickness`, [CornerRadius](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar.CornerRadius), [HasShadow](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar.HasShadow), `ItemSpacing`, `Padding`, and [UserInterfaceDensity](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar.UserInterfaceDensity) properties can be set to achieve an appearance like above. +} +@if (avalonia) { +### Secondary Toolbar + +[StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar) also works great out-of-the-box as a toolbar that can be placed in another container, such as within a panel. + +![Screenshot](../images/standalone-toolbar-toolwindow.png) + +*A standalone toolbar in a panel* +} + +@if (wpf) { ### Tool Window Toolbar [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar) also works great out-of-the-box as a toolbar that can be placed in another container, such as within a tool window from the [Actipro Docking/MDI product](../../docking/index.md). @@ -28,9 +44,32 @@ The toolbar's `Background`, `BorderBrush`, `BorderThickness`, [CornerRadius](xre ![Screenshot](../images/standalone-toolbar-toolwindow.png) *A standalone toolbar in a tool window* +} In this usage scenario, it's generally better to use the default appearance that is more compact. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + ... + + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" xmlns:docking="http://schemas.actiprosoftware.com/winfx/xaml/docking" @@ -63,6 +102,7 @@ xmlns:themes="http://schemas.actiprosoftware.com/winfx/xaml/themes" ``` +} ## Orientation @@ -90,6 +130,16 @@ Since the standalone toolbar doesn't dynamically adjust child control variants a Key tips in child controls are supported, but are not active by default and must be enabled by setting the attached [BarControlService](xref:@ActiproUIRoot.Controls.Bars.KeyTipService.IsRootKeyTipScopeProperty) property to `true`. +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + ... + +``` +} +@if (wpf) { ```xaml xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... @@ -97,6 +147,7 @@ xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" ... ``` +} After the toolbar is marked as a root key tip scope, pressing keys like Alt will activate key tip mode the same as with a ribbon. @@ -104,7 +155,7 @@ See the [Key Tips](../ribbon-features/key-tips.md) topic for more information on ## Screen Tips -The child controls support screen tips, which are formatted tool tips. Screen tips attempt to display below the [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar). +The child controls support screen tips, which are formatted tool tips. Screen tips attempt to display below the [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar) when horizontally oriented or to the far side when vertically oriented. See the [Screen Tips](../ribbon-features/screen-tips.md) topic for more information on screen tips. @@ -112,6 +163,21 @@ See the [Screen Tips](../ribbon-features/screen-tips.md) topic for more informat The optional companion [MVVM Library](../mvvm-support.md) defines a [StandaloneToolBarViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.StandaloneToolBarViewModel) class that is intended to be used as a view model for a [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar) control. +@if (avalonia) { +If a [StandaloneToolBarViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.StandaloneToolBarViewModel) instance is bound to the [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar).`DataContext`, a built-in `ControlTheme` with resource key [StandaloneToolBarControlTheme](xref:@ActiproUIRoot.Themes.Bars.Mvvm.BarsMvvmResourceKeys.StandaloneToolBarControlTheme) can be applied to configure bindings for all the view model's properties: + +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + ... + +``` +} +@if (wpf) { If a [StandaloneToolBarViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.StandaloneToolBarViewModel) instance is bound to the [StandaloneToolBar](xref:@ActiproUIRoot.Controls.Bars.StandaloneToolBar).`DataContext`, a built-in `Style` with resource key [BarsMvvmResourceKeys.StandaloneToolBarStyle](xref:@ActiproUIRoot.Themes.BarsMvvmResourceKeys.StandaloneToolBarStyle) can be applied to configure bindings for all the view model's properties: ```xaml @@ -125,6 +191,7 @@ xmlns:themes="http://schemas.actiprosoftware.com/winfx/xaml/themes" ... ``` +} > [!TIP] > See the [MVVM Support](../mvvm-support.md) topic for more information on how to use the library's view models and view templates to create and manage your application's bars controls with MVVM techniques. diff --git a/Documentation/topics/bars/troubleshooting.md b/Documentation/topics/bars/troubleshooting.md index a2ce4b5a..0a89a400 100644 --- a/Documentation/topics/bars/troubleshooting.md +++ b/Documentation/topics/bars/troubleshooting.md @@ -8,24 +8,30 @@ order: 410 This topic contains troubleshooting data specific to the Bars product. > [!NOTE] -> For some more troubleshooting information that relates both to this product as well as other WPF Studio products, please see the more general [Troubleshooting](../troubleshooting.md) topic. +> For some more troubleshooting information that relates both to this product as well as other Actipro @@PlatformName products, please see the more general [Troubleshooting](../troubleshooting.md) topic. +@if (wpf) { ## FileNotFoundException or DirectoryNotFoundException When Specifying Bitmap Image Sources If you use relative paths for your bitmap image sources, you might encounter a `FileNotFoundException` or `DirectoryNotFoundException` in some cases. This exception can occur behind the scenes where the image is being reloaded outside of its original XAML context and thus can lose its contextual information for determining a relative path. Using an absolute path via standard WPF pack syntax allows the image to be loaded properly in any scenario. Many of the Bars controls like the buttons use the [DynamicImage](../shared/windows-controls/dynamicimage.md) control in their templates, which is a Shared Library control that allows for disabled buttons to render their images in grayscale. Please see the [DynamicImage](../shared/windows-controls/dynamicimage.md) topic for more detailed information on this exception and exactly how to resolve it. +} ## Ribbon Shows in Designer but Disappears at Run-Time -This scenario could happen if you accidentally set a `Width` or `Height` on the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) control or one of its containers that causes the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) to be smaller than the [CollapseThresholdSize](xref:@ActiproUIRoot.Controls.Bars.Ribbon.CollapseThresholdSize). When the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) becomes smaller than [CollapseThresholdSize](xref:@ActiproUIRoot.Controls.Bars.Ribbon.CollapseThresholdSize) at run-time and [IsCollapsible](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsCollapsible) is set to `true`, the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) will hide. +This scenario could happen if you accidentally set a `Width` or `Height` on the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) control or one of its containers that causes the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) to be smaller than the @if (avalonia) { collapse threshold size }@if (wpf) { [CollapseThresholdSize](xref:@ActiproUIRoot.Controls.Bars.Ribbon.CollapseThresholdSize) }. When the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) becomes smaller than the @if (avalonia) { collapse threshold size }@if (wpf) { [CollapseThresholdSize](xref:@ActiproUIRoot.Controls.Bars.Ribbon.CollapseThresholdSize) } at run-time and [IsCollapsible](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsCollapsible) is set to `true`, the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) will hide. This scenario is most likely to occur when you are adjusting control layouts in the designer and adjust the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) or a parent container's size accidentally. -To resolve this issue, simply remove any explicit `Width` or `Height` setting on the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) or a parent container that is causing the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon)'s size be smaller than [CollapseThresholdSize](xref:@ActiproUIRoot.Controls.Bars.Ribbon.CollapseThresholdSize). Alternatively, change [IsCollapsible](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsCollapsible) to `false`. +To resolve this issue, simply remove any explicit `Width` or `Height` setting on the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon) or a parent container that is causing the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon)'s size be smaller than @if (avalonia) { collapse threshold size }@if (wpf) { [CollapseThresholdSize](xref:@ActiproUIRoot.Controls.Bars.Ribbon.CollapseThresholdSize) }. Alternatively, change [IsCollapsible](xref:@ActiproUIRoot.Controls.Bars.Ribbon.IsCollapsible) to `false`. +See the [Collapsing](ribbon-features/collapsing.md) topic for more details. + +@if (wpf) { ## Menus Are Anchored in the Incorrect Location This can occur when you are using a tablet PC or drawing tablet. The menu placement behavior will differ depending on whether the tablet support is configured for left-handed or right-handed use. This was designed so that menus do not appear under the user's hand. To resolve this issue, simply change the tablet support configuration to left-handed. +} diff --git a/Documentation/topics/docking/docking-window-features/docking-window-capabilities.md b/Documentation/topics/docking/docking-window-features/docking-window-capabilities.md index e08be927..4805f228 100644 --- a/Documentation/topics/docking/docking-window-features/docking-window-capabilities.md +++ b/Documentation/topics/docking/docking-window-features/docking-window-capabilities.md @@ -330,6 +330,19 @@ Gets or sets whether floating [ToolWindowContainer](xref:@ActiproUIRoot.Controls + + + + + diff --git a/Documentation/topics/docking/docking-window-features/floating-dock-hosts.md b/Documentation/topics/docking/docking-window-features/floating-dock-hosts.md index 04672c7d..058a7a02 100644 --- a/Documentation/topics/docking/docking-window-features/floating-dock-hosts.md +++ b/Documentation/topics/docking/docking-window-features/floating-dock-hosts.md @@ -89,6 +89,13 @@ private void OnDockSiteFloatingWindowOpening(object sender, FloatingWindowOpenin } ``` +## Double-Clicking Floating Tool Window Container Title Bars + +The [DockSite](xref:@ActiproUIRoot.Controls.Docking.DockSite).[FloatingToolWindowContainerTitleBarDoubleClickMode](xref:@ActiproUIRoot.Controls.Docking.DockSite.FloatingToolWindowContainerTitleBarDoubleClickMode) property determines the behavior for double-clicks on floating tool window container title bars. It can be set to one of these two values: + +- [ToggleMaximized](xref:@ActiproUIRoot.Controls.Docking.FloatingWindowTitleBarDoubleClickMode.ToggleMaximized) (default) - The floating window toggles between maximized and restored states. +- [Dock](xref:@ActiproUIRoot.Controls.Docking.FloatingWindowTitleBarDoubleClickMode.Dock) - The floating window docks back into another dock host. + @if (wpf) { ## Non-Hosted vs. Hosted Floating Windows diff --git a/Documentation/topics/licensing.md b/Documentation/topics/licensing.md index 8a326640..3c8e4429 100644 --- a/Documentation/topics/licensing.md +++ b/Documentation/topics/licensing.md @@ -152,7 +152,7 @@ The contents of a *licenses.licx* file are pretty simple. It needs a single lin This single line (update the version to match the one you use) should be added to the *licenses.licx* file in any project that uses Actipro @@PlatformName control or SyntaxEditor add-on products: ``` -ActiproSoftware.Products.ActiproLicenseToken, ActiproSoftware.Shared.Wpf, Version=24.1.3.0, Culture=neutral, PublicKeyToken=36ff2196ab5654b9 +ActiproSoftware.Products.ActiproLicenseToken, ActiproSoftware.Shared.Wpf, Version=24.1.4.0, Culture=neutral, PublicKeyToken=36ff2196ab5654b9 ``` > [!IMPORTANT] diff --git a/Documentation/topics/shared/windows-controls/avatar-group.md b/Documentation/topics/shared/windows-controls/avatar-group.md index bd6b2df7..d5a54c45 100644 --- a/Documentation/topics/shared/windows-controls/avatar-group.md +++ b/Documentation/topics/shared/windows-controls/avatar-group.md @@ -17,6 +17,8 @@ Use the [ItemLength](xref:@ActiproUIRoot.Controls.AvatarGroup.ItemLength) proper By default, each avatar will slightly overlap with the avatar that appears before it. Use the [OverlapPercentage](xref:@ActiproUIRoot.Controls.AvatarGroup.OverlapPercentage) property to define the extent of the overlap. The default value is `0.2` for a 20% overlap. +The [Orientation](xref:@ActiproUIRoot.Controls.AvatarGroup.Orientation) property determines if the non-overflowed avatars are arranged horizontally or vertically. The default is `Horizontal`. + ## Overflow Individual [Avatar](avatar.md) controls can optionally be overflowed when there is not enough room to display them all inline. When overflow is necessary, a button is added at the end of the group that, when clicked, will display the additional items in a popup. @@ -27,6 +29,8 @@ By default, the group will display as many avatars as possible in the space avai The overflow button indicates the number of overflowed items. Use the [OverflowStringFormat](xref:@ActiproUIRoot.Controls.AvatarGroup.OverflowStringFormat) property to customize how the count is formatted. The default is `"+{0}"`, where `{0}` is the placeholder for the current value of [OverflowedItemCount](xref:@ActiproUIRoot.Controls.AvatarGroup.OverflowedItemCount) (e.g., `"+9"`). +The [OverflowOrientation](xref:@ActiproUIRoot.Controls.AvatarGroup.OverflowOrientation) property determines if the overflowed avatars are arranged horizontally or vertically, and is configured separately from the [Orientation](xref:@ActiproUIRoot.Controls.AvatarGroup.Orientation) property. The default is `Horizontal`. + ## Configuring Avatar Items The [AvatarGroup](xref:@ActiproUIRoot.Controls.AvatarGroup) is an `ItemsControl` for [Avatar](avatar.md) controls. diff --git a/Samples/PrismIntegration/PrismIntegration.csproj b/Samples/PrismIntegration/PrismIntegration.csproj index 7ad12a32..e950ee5b 100644 --- a/Samples/PrismIntegration/PrismIntegration.csproj +++ b/Samples/PrismIntegration/PrismIntegration.csproj @@ -8,7 +8,7 @@ Actipro.ico - 24.1.3.0 + 24.1.4.0ActiproSoftware.Windows.PrismIntegrationActipro Software LLC @@ -32,7 +32,7 @@ - + \ No newline at end of file diff --git a/Samples/SampleBrowser/ActiproSoftware.References.props b/Samples/SampleBrowser/ActiproSoftware.References.props index bcac20d0..d7eb2d50 100644 --- a/Samples/SampleBrowser/ActiproSoftware.References.props +++ b/Samples/SampleBrowser/ActiproSoftware.References.props @@ -8,7 +8,7 @@ https://www.actiprosoftware.com/docs/controls/wpf/nuget --> - 24.1.3 + 24.1.4 diff --git a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/ComboBoxAndEditors/SampleMvvmControl.xaml.cs b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/ComboBoxAndEditors/SampleMvvmControl.xaml.cs index cfa78cef..ba62b2fa 100644 --- a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/ComboBoxAndEditors/SampleMvvmControl.xaml.cs +++ b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/ComboBoxAndEditors/SampleMvvmControl.xaml.cs @@ -191,7 +191,7 @@ private void InitializeRibbonViewModels() { Items = { new BarComboBoxViewModel("EnumValue", this.ComboBoxGalleryCommand, this.ComboBoxEnumItems) { - Description = "A combobox with items automated generated from the fields of an Enum type.", + Description = "A combobox with items automatically generated from the fields of an Enum type.", IsSynchronizedWithCurrentItem = true, IsUnmatchedTextAllowed = false, ItemTemplateSelector = new BarGalleryItemTemplateSelector(), diff --git a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/ComboBoxAndEditors/SampleXamlControl.xaml b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/ComboBoxAndEditors/SampleXamlControl.xaml index a5e4e7f9..5e0bde2e 100644 --- a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/ComboBoxAndEditors/SampleXamlControl.xaml +++ b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/ComboBoxAndEditors/SampleXamlControl.xaml @@ -175,7 +175,7 @@ + /// Gets or sets the selected font color category. + /// + /// The selected font color category. + public string SelectedFontColorCategory { + get => selectedFontColorCategory; + set { + if (selectedFontColorCategory != value) { + selectedFontColorCategory = value; + NotifyPropertyChanged(nameof(SelectedFontColorCategory)); + } + } + } + /// /// Gets or sets the current text highlight color. /// diff --git a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GalleryColorPickers/SampleXamlControl.xaml b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GalleryColorPickers/SampleXamlControl.xaml index c44e12c6..df53b63a 100644 --- a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GalleryColorPickers/SampleXamlControl.xaml +++ b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GalleryColorPickers/SampleXamlControl.xaml @@ -1,4 +1,4 @@ - + /// Gets or sets the selected color category. + /// + /// The selected color category. + public string SelectedColorCategory { + get => selectedColorCategory; + set { + if (selectedColorCategory != value) { + selectedColorCategory = value; + NotifyPropertyChanged(nameof(SelectedColorCategory)); + } + } + } + /// /// Gets or sets if an accented border is displayed around gallery items. /// diff --git a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GalleryInRibbon/SampleXamlControl.xaml b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GalleryInRibbon/SampleXamlControl.xaml index ea3ec446..0613e9af 100644 --- a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GalleryInRibbon/SampleXamlControl.xaml +++ b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GalleryInRibbon/SampleXamlControl.xaml @@ -1,4 +1,4 @@ - diff --git a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step02/MainWindow.xaml b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step02/MainWindow.xaml index 91f4f813..a5a0707a 100644 --- a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step02/MainWindow.xaml +++ b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step02/MainWindow.xaml @@ -49,12 +49,12 @@ EXPECTED OPERATION: diff --git a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step04/MainWindow.xaml b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step04/MainWindow.xaml index 83ce6116..607884ef 100644 --- a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step04/MainWindow.xaml +++ b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step04/MainWindow.xaml @@ -14,7 +14,7 @@ CHANGES SINCE LAST STEP: EXPECTED OPERATION: This step finally starts to populate the Ribbon. When this sample window is opened, the Ribbon - should display with a "Help" tab pre-selected. The tab should contain a "Learn More" group + should display with a "Help" tab pre-selected. The tab should contain a "Resources" group with a single "Help" button. Clicking the button should display the same message that has been displayed by the stand-alone Button in the previous steps. diff --git a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step04/SampleBarManager.cs b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step04/SampleBarManager.cs index 78fb0a09..5b90ba45 100644 --- a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step04/SampleBarManager.cs +++ b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step04/SampleBarManager.cs @@ -100,7 +100,7 @@ private void RegisterControlViewModels() { // derived from the Key or RoutedUICommand) and is typically defined as the first letter // of the first word. // - // This sample previously defined a Key of "Help", an explicit Label of "Help", an explicit + // This sample previously defined a Key of "Help", an explicit Label of "Help", and an explicit // KeyTipText of "H". Since the RoutedUICommand of ApplicationCommands.Help has a default // text of "Help" (en-US), both the Label and KeyTipText properties can be automatically // derived and do not need to be explicitly passed. diff --git a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step04/SampleWindowViewModel.cs b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step04/SampleWindowViewModel.cs index 727396f0..48454f91 100644 --- a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step04/SampleWindowViewModel.cs +++ b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step04/SampleWindowViewModel.cs @@ -55,7 +55,7 @@ public SampleWindowViewModel() { // has properties to define the content of each tab. // // Initialize the Tabs collection to include a RibbonTabViewModel that will define - // a "Help" tab containing a "Learn More" control group with a single "Help" button. + // a "Help" tab containing a "Resources" control group with a single "Help" button. Tabs = { // SAMPLE NOTE 4.2: diff --git a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step07/MainWindow.xaml b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step07/MainWindow.xaml index c746c156..c440054f 100644 --- a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step07/MainWindow.xaml +++ b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step07/MainWindow.xaml @@ -14,10 +14,10 @@ CHANGES SINCE LAST STEP: EXPECTED OPERATION: - When this sample window is opened, The Undo/Redo commands will be displayed in the Quick Access Toolbar (QAT) - shown below the Ribbon control. Clicking the drop-down arrow next to the QAT will display the - Cut/Copy/Paste commands in the Customize menu. Selecting any of the Cut/Copy/Paste commands in the - customize menu will add the corresponding command to the QAT. + When this sample window is opened, The Undo/Redo and Cut/Copy/Paste commands will be displayed in + the Quick Access Toolbar (QAT) shown below the Ribbon control. Clicking the drop-down arrow next to + the QAT will display the Cut/Copy/Paste commands in the Customize menu. Selecting any of the + Cut/Copy/Paste commands in the customize menu will add/remove the corresponding command to/from the QAT. --> diff --git a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step08/MainWindow.xaml b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step08/MainWindow.xaml index c232fbc2..a0078d09 100644 --- a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step08/MainWindow.xaml +++ b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/GettingStarted/Step08/MainWindow.xaml @@ -12,7 +12,7 @@ CHANGES SINCE LAST STEP: A note was added about the importance of using RibbonContainerPanel when working with Backstage. - See the SampleWindowViewModel class for details on configuring the Quick Access Toolbar. + See the SampleWindowViewModel class for details on configuring the Backstage. EXPECTED OPERATION: diff --git a/Samples/SampleBrowser/ProductSamples/GridsSamples/QuickStart/TreeListBoxDragDrop/CustomTreeListBoxItemAdapter.cs b/Samples/SampleBrowser/ProductSamples/GridsSamples/QuickStart/TreeListBoxDragDrop/CustomTreeListBoxItemAdapter.cs index d7128ced..e7ef5d5c 100644 --- a/Samples/SampleBrowser/ProductSamples/GridsSamples/QuickStart/TreeListBoxDragDrop/CustomTreeListBoxItemAdapter.cs +++ b/Samples/SampleBrowser/ProductSamples/GridsSamples/QuickStart/TreeListBoxDragDrop/CustomTreeListBoxItemAdapter.cs @@ -3,6 +3,7 @@ using System.Linq; using System.Text; using System.Windows; +using System.Windows.Controls; using ActiproSoftware.ProductSamples.GridsSamples.Common; using ActiproSoftware.Windows.Controls.Grids; @@ -214,6 +215,7 @@ public override void OnDrop(DragEventArgs e, TreeListBox targetControl, object t } // Move items + var movedItemModels = new List(); foreach (var item in items) { var nav = targetControl.GetItemNavigator(item); if (nav.GoToParent()) { @@ -233,12 +235,24 @@ public override void OnDrop(DragEventArgs e, TreeListBox targetControl, object t else break; + movedItemModels.Add(itemModel); + targetModel.Children.Insert(Math.Max(0, Math.Min(targetModel.Children.Count, targetDropIndex++)), itemModel); targetModel.IsExpanded = true; - + } + } + + if (movedItemModels.Any()) { + using (var batch = targetControl.CreateSelectionBatch()) { + // If the target control supports multi-select, ensure each moved item is reselected + if (targetControl.SelectionMode != SelectionMode.Single) { + targetControl.SelectedItem = null; + foreach (var movedItemModel in movedItemModels) + movedItemModel.IsSelected = true; + } + // Focus the last item - if (items[items.Count - 1] == item) - targetControl.FocusItem(itemModel); + targetControl.FocusItem(movedItemModels.Last()); } } } diff --git a/Samples/SampleBrowser/ProductSamples/SharedSamples/QuickStart/AvatarGroupIntro/MainControl.xaml b/Samples/SampleBrowser/ProductSamples/SharedSamples/QuickStart/AvatarGroupIntro/MainControl.xaml index b9d4ab3a..086c039e 100644 --- a/Samples/SampleBrowser/ProductSamples/SharedSamples/QuickStart/AvatarGroupIntro/MainControl.xaml +++ b/Samples/SampleBrowser/ProductSamples/SharedSamples/QuickStart/AvatarGroupIntro/MainControl.xaml @@ -28,6 +28,8 @@ + + diff --git a/Samples/SampleBrowser/Properties/AssemblyInfo.cs b/Samples/SampleBrowser/Properties/AssemblyInfo.cs index 7fb8e230..5753d51f 100644 --- a/Samples/SampleBrowser/Properties/AssemblyInfo.cs +++ b/Samples/SampleBrowser/Properties/AssemblyInfo.cs @@ -64,5 +64,5 @@ // // You can specify all the values or you can default the Revision and Build Numbers // by using the '*' as shown below: -[assembly: AssemblyVersion("24.1.3.0")] -[assembly: AssemblyInformationalVersion("24.1.3.0 - 20240424")] +[assembly: AssemblyVersion("24.1.4.0")] +[assembly: AssemblyInformationalVersion("24.1.4.0 - 20240910")] diff --git a/Samples/SampleBrowser/Properties/Licenses.licx b/Samples/SampleBrowser/Properties/Licenses.licx index 3cc8c200..ee4adc6a 100644 --- a/Samples/SampleBrowser/Properties/Licenses.licx +++ b/Samples/SampleBrowser/Properties/Licenses.licx @@ -1 +1 @@ -ActiproSoftware.Products.ActiproLicenseToken, ActiproSoftware.Shared.Wpf, Version=24.1.3.0, Culture=neutral, PublicKeyToken=36ff2196ab5654b9 +ActiproSoftware.Products.ActiproLicenseToken, ActiproSoftware.Shared.Wpf, Version=24.1.4.0, Culture=neutral, PublicKeyToken=36ff2196ab5654b9 diff --git a/Samples/SampleBrowser/SampleBrowser.csproj b/Samples/SampleBrowser/SampleBrowser.csproj index 63458094..fa149003 100644 --- a/Samples/SampleBrowser/SampleBrowser.csproj +++ b/Samples/SampleBrowser/SampleBrowser.csproj @@ -14,7 +14,7 @@ Images\Icons\Actipro.ico Properties\app.manifest - 24.1.3.0 + 24.1.4.0 ActiproSoftware diff --git a/Samples/SampleBrowser/SampleBrowser/Documents/ReleaseHistories/v24.1.xaml b/Samples/SampleBrowser/SampleBrowser/Documents/ReleaseHistories/v24.1.xaml index 7811dda9..4aaa5ad3 100644 --- a/Samples/SampleBrowser/SampleBrowser/Documents/ReleaseHistories/v24.1.xaml +++ b/Samples/SampleBrowser/SampleBrowser/Documents/ReleaseHistories/v24.1.xaml @@ -10,6 +10,70 @@ + 12/17/2024 - Version 24.1.4 + Bars + + + + + + + + + + + + + Docking + + + + + + + + + Editors + + + + + Grids + + + + + SyntaxEditor + + + + + + + + + .NET Languages Add-on + + + + + Python Language Add-on + + + + Views + + + + Shared + + + + + + + + 9/9/2024 - Version 24.1.3 Bar Code diff --git a/Samples/WindowsWorkflowIntegration/WindowsWorkflowIntegration.csproj b/Samples/WindowsWorkflowIntegration/WindowsWorkflowIntegration.csproj index 92580c4a..be2c0287 100644 --- a/Samples/WindowsWorkflowIntegration/WindowsWorkflowIntegration.csproj +++ b/Samples/WindowsWorkflowIntegration/WindowsWorkflowIntegration.csproj @@ -8,7 +8,7 @@ Actipro.ico - 24.1.3.0 + 24.1.4.0 ActiproSoftware.Windows.WindowsWorkflowIntegration Actipro Software LLC @@ -33,8 +33,8 @@ - - + + \ No newline at end of file diff --git a/Source/Bars.Mvvm/Bars.Mvvm.csproj b/Source/Bars.Mvvm/Bars.Mvvm.csproj index fad11197..b0d32149 100644 --- a/Source/Bars.Mvvm/Bars.Mvvm.csproj +++ b/Source/Bars.Mvvm/Bars.Mvvm.csproj @@ -10,7 +10,7 @@ Common view models, templates, and other types used when implementing Bars controls with MVVM (Model-View-ViewModel) patterns.Actipro UI Controls WPF XAML MVVM Model View ViewModel Bars - 24.1.3.0 + 24.1.4.0ActiproSoftwareActipro Software LLC @@ -34,7 +34,7 @@ - + diff --git a/Source/Bars.Mvvm/Products/Bars.Mvvm/AssemblyInfo.cs b/Source/Bars.Mvvm/Products/Bars.Mvvm/AssemblyInfo.cs index 941a6a66..06264279 100644 --- a/Source/Bars.Mvvm/Products/Bars.Mvvm/AssemblyInfo.cs +++ b/Source/Bars.Mvvm/Products/Bars.Mvvm/AssemblyInfo.cs @@ -46,5 +46,5 @@ // You can specify all the values or you can default the Revision and Build Numbers // by using the '*' as shown below: -[assembly: AssemblyVersion("24.1.3.0")] // WPF -[assembly: AssemblyInformationalVersion("24.1.3.0")] // WPF +[assembly: AssemblyVersion("24.1.4.0")] // WPF +[assembly: AssemblyInformationalVersion("24.1.4.0")] // WPF diff --git a/Source/Bars.Mvvm/UI/Controls.Bars.Mvvm/ViewModels/BarControls/BarGalleryViewModel.cs b/Source/Bars.Mvvm/UI/Controls.Bars.Mvvm/ViewModels/BarControls/BarGalleryViewModel.cs index 48222e32..5a5abb2b 100644 --- a/Source/Bars.Mvvm/UI/Controls.Bars.Mvvm/ViewModels/BarControls/BarGalleryViewModel.cs +++ b/Source/Bars.Mvvm/UI/Controls.Bars.Mvvm/ViewModels/BarControls/BarGalleryViewModel.cs @@ -38,6 +38,7 @@ public class BarGalleryViewModel : BarGalleryViewModelBase, IHasVariantImages { private int minMenuColumnCount = 1; private ICommand popupOpeningCommand; private IBarGalleryItemViewModel selectedItem; + private string selectedFilterCategory; private ItemCollapseBehavior toolBarItemCollapseBehavior = ItemCollapseBehavior.Default; private ItemVariantBehavior toolBarItemVariantBehavior = ItemVariantBehavior.AlwaysSmall; private bool useAccentedItemBorder; @@ -477,6 +478,20 @@ public ICommand PopupOpeningCommand { } } + /// + /// Gets or sets the selected filter category. + /// + /// The selected filter category. + public string SelectedFilterCategory { + get => selectedFilterCategory; + set { + if (selectedFilterCategory != value) { + selectedFilterCategory = value; + this.NotifyPropertyChanged(nameof(SelectedFilterCategory)); + } + } + } + /// /// Gets or sets the selected item. /// diff --git a/Source/Bars.Mvvm/UI/Themes/BarsMvvmResourceDictionary.xaml b/Source/Bars.Mvvm/UI/Themes/BarsMvvmResourceDictionary.xaml index adf1abf7..99669dcf 100644 --- a/Source/Bars.Mvvm/UI/Themes/BarsMvvmResourceDictionary.xaml +++ b/Source/Bars.Mvvm/UI/Themes/BarsMvvmResourceDictionary.xaml @@ -259,6 +259,7 @@ MinMediumColumnCount="{Binding MinMediumRibbonColumnCount}" MinMenuColumnCount="{Binding MinMenuColumnCount}" PopupOpeningCommand="{Binding PopupOpeningCommand}" + SelectedFilterCategory="{Binding SelectedFilterCategory}" SelectedItem="{Binding SelectedItem, Mode=TwoWay}" SmallImageSource="{Binding SmallImageSource}" Title="{Binding Title}" @@ -300,6 +301,7 @@ MinItemHeight="{Binding MinItemHeight}" MinItemWidth="{Binding MinItemWidth}" ResizeMode="{Binding MenuResizeMode}" + SelectedFilterCategory="{Binding SelectedFilterCategory}" SelectedItem="{Binding SelectedItem, Mode=TwoWay}" SmallImageSource="{Binding SmallImageSource}" Title="{Binding Title}" diff --git a/Source/DataGrid.Contrib/DataGrid.Contrib.csproj b/Source/DataGrid.Contrib/DataGrid.Contrib.csproj index a447ad77..89dbd8b6 100644 --- a/Source/DataGrid.Contrib/DataGrid.Contrib.csproj +++ b/Source/DataGrid.Contrib/DataGrid.Contrib.csproj @@ -10,7 +10,7 @@ Common extensions, behaviors, and themes for the WPF DataGrid control. Actipro UI Controls WPF XAML DataGrid - 24.1.3.0 + 24.1.4.0 ActiproSoftware Actipro Software LLC @@ -34,7 +34,7 @@ - + diff --git a/Source/DataGrid.Contrib/Products/DataGrid/Contrib/AssemblyInfo.cs b/Source/DataGrid.Contrib/Products/DataGrid/Contrib/AssemblyInfo.cs index 566084e9..4c52abef 100644 --- a/Source/DataGrid.Contrib/Products/DataGrid/Contrib/AssemblyInfo.cs +++ b/Source/DataGrid.Contrib/Products/DataGrid/Contrib/AssemblyInfo.cs @@ -52,8 +52,8 @@ // You can specify all the values or you can default the Revision and Build Numbers // by using the '*' as shown below: -[assembly: AssemblyVersion("24.1.3.0")] // WPF -[assembly: AssemblyInformationalVersion("24.1.3.0")] // WPF +[assembly: AssemblyVersion("24.1.4.0")] // WPF +[assembly: AssemblyInformationalVersion("24.1.4.0")] // WPF namespace ActiproSoftware.Products.DataGrid.Contrib { diff --git a/Source/Editors.Interop.DataGrid/Editors.Interop.DataGrid.csproj b/Source/Editors.Interop.DataGrid/Editors.Interop.DataGrid.csproj index 5a949d0b..2e1d7f6b 100644 --- a/Source/Editors.Interop.DataGrid/Editors.Interop.DataGrid.csproj +++ b/Source/Editors.Interop.DataGrid/Editors.Interop.DataGrid.csproj @@ -10,7 +10,7 @@ Provides interoperability between Actipro's WPF Editors product and the WPF DataGrid. Actipro UI Controls WPF XAML Editors DataGrid - 24.1.3.0 + 24.1.4.0 ActiproSoftware Actipro Software LLC @@ -34,7 +34,7 @@ - + diff --git a/Source/Editors.Interop.DataGrid/Products/Editors.Interop.DataGrid/AssemblyInfo.cs b/Source/Editors.Interop.DataGrid/Products/Editors.Interop.DataGrid/AssemblyInfo.cs index a939b2ea..2cb061ec 100644 --- a/Source/Editors.Interop.DataGrid/Products/Editors.Interop.DataGrid/AssemblyInfo.cs +++ b/Source/Editors.Interop.DataGrid/Products/Editors.Interop.DataGrid/AssemblyInfo.cs @@ -43,5 +43,5 @@ // You can specify all the values or you can default the Revision and Build Numbers // by using the '*' as shown below: -[assembly: AssemblyVersion("24.1.3.0")] // WPF -[assembly: AssemblyInformationalVersion("24.1.3.0")] // WPF +[assembly: AssemblyVersion("24.1.4.0")] // WPF +[assembly: AssemblyInformationalVersion("24.1.4.0")] // WPF
+[DockSite](xref:@ActiproUIRoot.Controls.Docking.DockSite).[FloatingToolWindowContainerTitleBarDoubleClickMode](xref:@ActiproUIRoot.Controls.Docking.DockSite.FloatingToolWindowContainerTitleBarDoubleClickMode) Property + + + +Gets or sets what happens when floating [ToolWindowContainer](xref:@ActiproUIRoot.Controls.Docking.ToolWindowContainer) controls' title bars are double-clicked. The default value is [ToggleMaximized](xref:@ActiproUIRoot.Controls.Docking.FloatingWindowTitleBarDoubleClickMode.ToggleMaximized). + +
+ [DockSite](xref:@ActiproUIRoot.Controls.Docking.DockSite).[HasTabCloseButtons](xref:@ActiproUIRoot.Controls.Docking.TabbedMdiHost.HasTabCloseButtons) Property