diff --git a/Documentation/topics/bars/controls/button.md b/Documentation/topics/bars/controls/button.md index 555b25ce..a5960e56 100644 --- a/Documentation/topics/bars/controls/button.md +++ b/Documentation/topics/bars/controls/button.md @@ -118,10 +118,12 @@ 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), falling back to [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarButton.SmallImageSource) if a medium image is not available. +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). -[BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) instances can optionally define a [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallImageSource) that appears in the menu's icon column. When [UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.UseLargeSize) is set to create a large menu item, the [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeImageSource) property is used instead. When the menu item is checked, a highlight box will appear around the image. If no image is specified, a standard check glyph will be used in place of the image. +> [!TIP] +> See the [Control Basics](control-basics.md) topic for more detail on the fallback logic for button images. +[BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) instances can optionally define a [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallImageSource) that appears in the menu's icon column. When [UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.UseLargeSize) is set to create a large menu item, the [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeImageSource) property is used instead. When the menu item is checked, a highlight box will appear around the image. If no image is specified, a standard check glyph will be used in place of the image. ### Description (BarMenuItem only) diff --git a/Documentation/topics/bars/controls/control-basics.md b/Documentation/topics/bars/controls/control-basics.md index 3583a042..6306c871 100644 --- a/Documentation/topics/bars/controls/control-basics.md +++ b/Documentation/topics/bars/controls/control-basics.md @@ -89,20 +89,29 @@ Some controls support a single image size, while other controls with variant siz | Medium | 24x24 | Medium images are only used in [Simplified layout mode](../ribbon-features/layout-and-density.md) for some controls. | | Large | 32x32 | Large images are used in certain controls when in large variant sizes. | -When a button is in a ribbon with [Simplified layout mode](../ribbon-features/layout-and-density.md) active, it will fall back to using its small image if a medium image is not available. - #### Fallback Label and Images If an image is not defined and is vital to the normal appearance of the control, a fallback display mechanism can occur, primarily in buttons. In many cases, a missing image for small and medium variant size buttons will result in the label being displayed instead. -In other cases, such as when the control is within the ribbon's [quick access toolbar](../ribbon-features/quick-access-toolbar.md) or when the control is a collapsed ribbon group, then a default fallback image will be used. +In other cases, such as when the control is within the ribbon's [quick access toolbar](../ribbon-features/quick-access-toolbar.md) or when the control is a collapsed ribbon group, then a default missing fallback image will be used. ![Screenshot](../images/fallback-image.png) *The fallback image* +The following table describes the priority order of properties (e.g., `SmallImageSource`, `LargeImageSource`) used to resolve an image for a desired image size. + +| Desired Image Size | Resolution Priority | +|-----|-----| +| Small (16x16) | Small, Large (downscaled), Medium (downscaled), Missing (if no label visible) | +| Medium (24x24) | Medium, Small (centered), Large (downscaled), Missing (if no label visible) | +| Large (32x32) | Large, Medium (centered), Small (centered), Missing | + +> [!TIP] +> When using a vector image for a button with the intention of using a single image for all image sizes, it is best to make a single 32x32 size vector image and assign it to the button's `LargeImageSource` property. Per the table above, a `Large` image can scale down as a fallback for other image sizes. When using raster images, it is much better to use a distinct image design for the `Large` and `Small` image sizes at a minimum. + ### Title An optional string `Title` can be specified, which is intended to override the control's `Label` when displayed in screen tips and customization UI. diff --git a/Documentation/topics/bars/controls/gallery.md b/Documentation/topics/bars/controls/gallery.md index dfb10e5e..2f8a618d 100644 --- a/Documentation/topics/bars/controls/gallery.md +++ b/Documentation/topics/bars/controls/gallery.md @@ -324,6 +324,10 @@ The gallery's `SelectedItem` property may be set at any time to alter the select The [IsSelectionSupported](xref:@ActiproUIRoot.Controls.Bars.Primitives.BarGalleryBase.IsSelectionSupported) property, which defaults to `true`, can be set to `false` to prevent a selection from being retained when an item is clicked. It does this by automatically clearing the `SelectedItem` after a selection is made. This feature is handy for galleries that should take an action when an item is clicked, such as a gallery that inserts a symbol into a document based on the item that was clicked. +### Automatically Scrolling to the Selected Item (RibbonGallery only) + +The [RibbonGallery](xref:@ActiproUIRoot.Controls.Bars.RibbonGallery).[CanAutoScrollToSelectedItem](xref:@ActiproUIRoot.Controls.Bars.RibbonGallery.CanAutoScrollToSelectedItem) property, which defaults to `false`, can be set to `true` to automatically scroll to the in-ribbon gallery's selected item when the selection changes. This ensures that external changes to the selection keep the newly-selected item visible in the user interface. + ### Item Templates Gallery controls generate a [BarGalleryItem](xref:@ActiproUIRoot.Controls.Bars.BarGalleryItem) container for each gallery item in the gallery's `ItemsSource`. diff --git a/Documentation/topics/bars/controls/popup-button.md b/Documentation/topics/bars/controls/popup-button.md index 8a193055..c870ba5a 100644 --- a/Documentation/topics/bars/controls/popup-button.md +++ b/Documentation/topics/bars/controls/popup-button.md @@ -124,7 +124,10 @@ 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), falling back to [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.SmallImageSource) if a medium image is not available. +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). + +> [!TIP] +> See the [Control Basics](control-basics.md) topic for more detail on the fallback logic for button images. [BarMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem) instances can optionally define a [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallImageSource) that appears in the menu's icon column. When [UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.UseLargeSize) is set to create a large menu item, the [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeImageSource) property is used instead. diff --git a/Documentation/topics/bars/controls/split-button.md b/Documentation/topics/bars/controls/split-button.md index 848f6352..0ebc3cc4 100644 --- a/Documentation/topics/bars/controls/split-button.md +++ b/Documentation/topics/bars/controls/split-button.md @@ -130,7 +130,10 @@ 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), falling back to [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarPopupButton.SmallImageSource) if a medium image is not available. +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). + +> [!TIP] +> See the [Control Basics](control-basics.md) topic for more detail on the fallback logic for button images. [BarSplitMenuItem](xref:@ActiproUIRoot.Controls.Bars.BarSplitMenuItem) instances can optionally define a [SmallImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.SmallImageSource) that appears in the menu's icon column. When [UseLargeSize](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.UseLargeSize) is set to create a large menu item, the [LargeImageSource](xref:@ActiproUIRoot.Controls.Bars.BarMenuItem.LargeImageSource) property is used instead. When the menu item is checked, a highlight box will appear around the image. If no image is specified, a standard check glyph will be used in place of the image. diff --git a/Documentation/topics/bars/controls/using-custom-controls.md b/Documentation/topics/bars/controls/using-custom-controls.md index 9fae7fab..46fdafc1 100644 --- a/Documentation/topics/bars/controls/using-custom-controls.md +++ b/Documentation/topics/bars/controls/using-custom-controls.md @@ -111,6 +111,7 @@ xmlns:editors="http://schemas.actiprosoftware.com/winfx/xaml/editors" bars:BarControlService.Key="Minimum" bars:BarControlService.Label="Minimum" bars:BarControlService.PanelSpacingSuggestion="Both" + bars:BarControlService.SmallImageSource="/Images/Minimum16.png" Width="60" MinHeight="24" MaxHeight="30" UsageContext="ToolBar" themes:ThemeProperties.CornerRadius="3" @@ -120,6 +121,8 @@ 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. + ## 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. diff --git a/Documentation/topics/bars/mvvm-support.md b/Documentation/topics/bars/mvvm-support.md index ed51aab4..1743ae7f 100644 --- a/Documentation/topics/bars/mvvm-support.md +++ b/Documentation/topics/bars/mvvm-support.md @@ -187,7 +187,8 @@ The following table shows the ribbon footer content view model types defined in | Name | Description | |-----|-----| -| [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 [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). | #### Gallery Item View Models diff --git a/Documentation/topics/bars/ribbon-features/backstage.md b/Documentation/topics/bars/ribbon-features/backstage.md index 5e04f567..c2335966 100644 --- a/Documentation/topics/bars/ribbon-features/backstage.md +++ b/Documentation/topics/bars/ribbon-features/backstage.md @@ -115,10 +115,14 @@ When there are not many tabs or buttons to display in the backstage, the backsta ## Auto-Selecting a Tab When Backstage Opens +The first tab is auto-selected if no tab is currently selected when the backstage opens or when the [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage).[CanSelectFirstTabOnOpen](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage.CanSelectFirstTabOnOpen) property is `true`, which is that property's default value. + The [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage).[IsOpen](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage.IsOpen) property gets or sets whether the backstage is currently open. A related [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage).[IsOpenChanged](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage.IsOpenChanged) event is raised whenever that property changes. This is an ideal place to initialize the backstage so that a certain tab is always selected when it opens. The event handler for the [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage).[IsOpenChanged](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage.IsOpenChanged) event can check to see if the backstage is being opened and, if so, ensure the [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage).`SelectedItem` property is set to the desired tab. +Set the [RibbonBackstage](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage).[CanSelectFirstTabOnOpen](xref:@ActiproUIRoot.Controls.Bars.RibbonBackstage.CanSelectFirstTabOnOpen) property to `false` if the selected tab will be set programmatically. + ## 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. diff --git a/Documentation/topics/bars/ribbon-features/footer.md b/Documentation/topics/bars/ribbon-features/footer.md index dee414ef..c593eca4 100644 --- a/Documentation/topics/bars/ribbon-features/footer.md +++ b/Documentation/topics/bars/ribbon-features/footer.md @@ -48,14 +48,23 @@ The footer may also be defined by setting the [Ribbon](xref:@ActiproUIRoot.Contr The optional companion [MVVM Library](../mvvm-support.md) defines a [RibbonFooterViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel) class that is intended to be used as a view model for a [RibbonFooterControl](xref:@ActiproUIRoot.Controls.Bars.RibbonFooterControl) control, and the [BarControlTemplateSelector](xref:@ActiproUIRoot.Controls.Bars.Mvvm.BarControlTemplateSelector) class in the library generates a [RibbonFooterControl](xref:@ActiproUIRoot.Controls.Bars.RibbonFooterControl) for that view model. +### Simple Content + A [RibbonFooterSimpleContentViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterSimpleContentViewModel) instance may be assigned to the [RibbonFooterViewModel](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel).[Content](xref:@ActiproUIRoot.Controls.Bars.Mvvm.RibbonFooterViewModel.Content) property. This simple content view model supports easy definition of an image and text message for the footer. +### 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. + +> [!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. + > [!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. ## Showing / Hiding the Footer -The ribbon will display the footer as long as the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[FooterContent](xref:@ActiproUIRoot.Controls.Bars.Ribbon.FooterContent) property is defined. To show the footer, set the [FooterContent](xref:@ActiproUIRoot.Controls.Bars.Ribbon.FooterContent) property to the desired content. To hide the footer, set the [FooterContent](xref:@ActiproUIRoot.Controls.Bars.Ribbon.FooterContent) property to `null`. +The ribbon will display the footer as long as the [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[FooterContent](xref:@ActiproUIRoot.Controls.Bars.Ribbon.FooterContent) property is defined. To show the footer, set the [FooterContent](xref:@ActiproUIRoot.Controls.Bars.Ribbon.FooterContent) property to the desired content. To hide the footer, set the [FooterContent](xref:@ActiproUIRoot.Controls.Bars.Ribbon.FooterContent) property to `null` or invoke the command defined by the [ClearFooterCommand](xref:@ActiproUIRoot.Controls.Bars.Ribbon.ClearFooterCommand) property. > [!IMPORTANT] > The ribbon has an altered appearance based on the presence of the footer, so changing the `Visibility` property of a footer control is not sufficient to properly hide the footer. @@ -70,4 +79,70 @@ Instead of setting the `Background` property directly, the [RibbonFooterControl] 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. \ No newline at end of file +> See the "Footer" Bars Ribbon QuickStart of the Sample Browser application for a full demonstration of working with the ribbon footer. + +## 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. + +- **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`. + +### 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. + +> [!IMPORTANT] +> Setting the `Background` property directly will prevent the background color from changing to match the current [InfoBarSeverity](xref:@ActiproUIRoot.Controls.InfoBarSeverity). + +### Closing + +When [InfoBar](xref:@ActiproUIRoot.Controls.InfoBar).[CanClose](xref:@ActiproUIRoot.Controls.InfoBar.CanClose) is set to `true`, a **Close Button** is displayed. By default, clicking this button will hide the [InfoBar](xref:@ActiproUIRoot.Controls.InfoBar) (i.e., set `Visibility` to `Collapsed`), but hiding the control does not effectively hide the ribbon's footer. As noted in the "Showing / Hiding the Footer" section above, the footer must be set to `null` to properly hide the footer. + +The easiest solution is to bind the [InfoBar](xref:@ActiproUIRoot.Controls.InfoBar).[CloseButtonCommand](xref:@ActiproUIRoot.Controls.InfoBar.CloseButtonCommand) to the ancestor [Ribbon](xref:@ActiproUIRoot.Controls.Bars.Ribbon).[ClearFooterCommand](xref:@ActiproUIRoot.Controls.Bars.Ribbon.ClearFooterCommand) so clicking the **Close Button** will clear the footer. Otherwise, use a custom command or listen to the [InfoBar](xref:@ActiproUIRoot.Controls.InfoBar).[CloseButtonClick](xref:@ActiproUIRoot.Controls.InfoBar.CloseButtonClick) event and clear the footer as noted in the "Showing / Hiding the Footer" section above. + +### Example + +The following example fully demonstrates one way to use an [InfoBar](../../shared/windows-controls/info-bar.md) on a footer: + +```xaml +xmlns:bars="http://schemas.actiprosoftware.com/winfx/xaml/bars" +xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared" +... + + + + + + + + + + + + + + + + + + + +``` \ No newline at end of file diff --git a/Documentation/topics/editors/editboxes/enumeditbox.md b/Documentation/topics/editors/editboxes/enumeditbox.md index 3fc6cb08..fb12443e 100644 --- a/Documentation/topics/editors/editboxes/enumeditbox.md +++ b/Documentation/topics/editors/editboxes/enumeditbox.md @@ -93,7 +93,7 @@ Sometimes it is helpful to display an alternate text version of an enumeration v This scenario is fully supported by [EnumEditBox](xref:@ActiproUIRoot.Controls.Editors.EnumEditBox). A `System.ComponentModel.DataAnnotations.DisplayAttribute` can be applied to a value to give it an alternate textual description. Then as long as the [UseDisplayAttributes](xref:@ActiproUIRoot.Controls.Editors.EnumEditBox.UseDisplayAttributes) property is set to `true`, that alternate text will be used. -If the `DisplayAttribute.ResourceType` property is left blank, it will use the direct value specified by the `Name` property. Otherwise, it will look in the specified resource `Type` for a localized resource value within the property indicated by `Name`. +If the `DisplayAttribute.ResourceType` property is left blank, it will use the direct value specified by the `Name` property. Otherwise, it will look in the specified resource `Type` for a localized resource value within the property indicated by `Name`. If the `Name` property is undefined, the `ShortName` property will be used instead. In this example, the `DisplayAttribute` will look for a property named `MyFirstValue` in the string resources type `MyResources` and use that property's value: @@ -120,6 +120,8 @@ By default, values are listed in the order they are defined. The exception is t Sorting can be altered by implementing a custom `IComparer` class and assigning it to the [EnumSortComparer](xref:@ActiproUIRoot.Controls.Editors.EnumEditBox.EnumSortComparer) property. The [EnumValueNameSortComparer](xref:@ActiproUIRoot.Controls.Editors.Primitives.EnumValueNameSortComparer).[Instance](xref:@ActiproUIRoot.Controls.Editors.Primitives.EnumValueNameSortComparer.Instance) static property provides access to a pre-built comparer for listing enumeration values alphabetically by name. +Alternatively, the `DisplayAttribute.Order` property can be used to define the sort order if the [UseDisplayAttributes](xref:@ActiproUIRoot.Controls.Editors.EnumEditBox.UseDisplayAttributes) property is set to `true` and a custom [EnumSortComparer](xref:@ActiproUIRoot.Controls.Editors.EnumEditBox.EnumSortComparer) is undefined. Values that define a `DisplayAttribute.Order` will always be sorted before values that do not define the attribute. + ## Hiding Enumeration Values By default, all values are listed in the control's popup and when cycling through values using arrow keys. If you wish to hide a specific value from the end user, use `EditorBrowsableAttribute` on the value with `EditorBrowsableState.Never`. diff --git a/Documentation/topics/editors/pickers/enumpicker.md b/Documentation/topics/editors/pickers/enumpicker.md index 7e14b8d8..eedec520 100644 --- a/Documentation/topics/editors/pickers/enumpicker.md +++ b/Documentation/topics/editors/pickers/enumpicker.md @@ -23,7 +23,7 @@ Sometimes it is helpful to display an alternate text version of an enumeration v This scenario is fully supported by [EnumPicker](xref:@ActiproUIRoot.Controls.Editors.EnumPicker). A `System.ComponentModel.DataAnnotations.DisplayAttribute` can be applied to a value to give it an alternate textual description. Then as long as the [UseDisplayAttributes](xref:@ActiproUIRoot.Controls.Editors.EnumPicker.UseDisplayAttributes) property is set to `true`, that alternate text will be used. -If the `DisplayAttribute.ResourceType` property is left blank, it will use the direct value specified by the `Name` property. Otherwise, it will look in the specified resource `Type` for a localized resource value within the property indicated by `Name`. +If the `DisplayAttribute.ResourceType` property is left blank, it will use the direct value specified by the `Name` property. Otherwise, it will look in the specified resource `Type` for a localized resource value within the property indicated by `Name`. If the `Name` property is undefined, the `ShortName` property will be used instead. In this example, the `DisplayAttribute` will look for a property named `MyFirstValue` in the string resources type `MyResources` and use that property's value: @@ -50,6 +50,8 @@ By default, values are listed in the order they are defined. The exception is t Sorting can be altered by implementing a custom `IComparer` class and assigning it to the [EnumSortComparer](xref:@ActiproUIRoot.Controls.Editors.EnumPicker.EnumSortComparer) property. The [EnumValueNameSortComparer](xref:@ActiproUIRoot.Controls.Editors.Primitives.EnumValueNameSortComparer).[Instance](xref:@ActiproUIRoot.Controls.Editors.Primitives.EnumValueNameSortComparer.Instance) static property provides access to a pre-built comparer for listing enumeration values alphabetically by name. +Alternatively, the `DisplayAttribute.Order` property can be used to define the sort order if the [UseDisplayAttributes](xref:@ActiproUIRoot.Controls.Editors.EnumPicker.UseDisplayAttributes) property is set to `true` and a custom [EnumSortComparer](xref:@ActiproUIRoot.Controls.Editors.EnumPicker.EnumSortComparer) is undefined. Values that define a `DisplayAttribute.Order` will always be sorted before values that do not define the attribute. + ## Hiding Enumeration Values By default, all values are listed in the control. If you wish to hide a specific value from the end user, use `EditorBrowsableAttribute` on the value with `EditorBrowsableState.Never`. diff --git a/Documentation/topics/licensing.md b/Documentation/topics/licensing.md index ae787295..7086cecd 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.1.0, Culture=neutral, PublicKeyToken=36ff2196ab5654b9 +ActiproSoftware.Products.ActiproLicenseToken, ActiproSoftware.Shared.Wpf, Version=24.1.2.0, Culture=neutral, PublicKeyToken=36ff2196ab5654b9 ``` > [!IMPORTANT] diff --git a/Documentation/topics/recent-updates.md b/Documentation/topics/recent-updates.md index 14fe9d31..f477a44f 100644 --- a/Documentation/topics/recent-updates.md +++ b/Documentation/topics/recent-updates.md @@ -9,9 +9,20 @@ WPF Studio's documentation has frequent updates, so this topic is the best place If you are looking for a list of recently added major new features to WPF Studio products, please see the Sample Browser's Recent Updates page instead. +## Updates for v24.1.2 + +- **Bars:** Updated [Footer](bars/ribbon-features/footer.md) documentation with details on using [InfoBar](shared/windows-controls/info-bar.md) in the ribbon footer. + +- **Views:** Added documentation for the new [SettingsCard](views/controls/settings-card.md), [SettingsExpander](xref:@ActiproUIRoot.Controls.Views.SettingsExpander), and [SettingsGroup](xref:@ActiproUIRoot.Controls.Views.SettingsGroup) controls. + +- **Shared:** Added documentation for the new [Card](shared/windows-controls/card.md) and [InfoBar](shared/windows-controls/info-bar.md) controls. + +- **Shared:** Added documentation for [Template Selectors](shared/windows-controls/template-selectors.md) which includes the new [ImageTemplateSelector](xref:@ActiproUIRoot.Controls.ImageTemplateSelector). + ## Updates for v24.1.0 - **Shared:** Restructured [User Prompt](shared/windows-controls/user-prompt/index.md) documentation across multiple topics. +- **Shared:** Added documentation for the new [Avatar](shared/windows-controls/avatar.md), [AvatarGroup](shared/windows-controls/avatar-group.md), [Badge](shared/windows-controls/badge.md), and [CircularProgressBar](shared/windows-controls/circular-progressbar.md) controls. - **All:** Updated [Sample Code and QuickStarts](quick-starts.md) topic. diff --git a/Documentation/topics/shared/images/card-padding.png b/Documentation/topics/shared/images/card-padding.png new file mode 100644 index 00000000..f0131f9e Binary files /dev/null and b/Documentation/topics/shared/images/card-padding.png differ diff --git a/Documentation/topics/shared/images/card.png b/Documentation/topics/shared/images/card.png new file mode 100644 index 00000000..4f1042f1 Binary files /dev/null and b/Documentation/topics/shared/images/card.png differ diff --git a/Documentation/topics/shared/images/info-bar-action.png b/Documentation/topics/shared/images/info-bar-action.png new file mode 100644 index 00000000..80bb2213 Binary files /dev/null and b/Documentation/topics/shared/images/info-bar-action.png differ diff --git a/Documentation/topics/shared/images/info-bar-content.png b/Documentation/topics/shared/images/info-bar-content.png new file mode 100644 index 00000000..83877fe0 Binary files /dev/null and b/Documentation/topics/shared/images/info-bar-content.png differ diff --git a/Documentation/topics/shared/images/info-bar-severity.png b/Documentation/topics/shared/images/info-bar-severity.png new file mode 100644 index 00000000..560477cc Binary files /dev/null and b/Documentation/topics/shared/images/info-bar-severity.png differ diff --git a/Documentation/topics/shared/images/info-bar-wrapping.png b/Documentation/topics/shared/images/info-bar-wrapping.png new file mode 100644 index 00000000..0e77f2fe Binary files /dev/null and b/Documentation/topics/shared/images/info-bar-wrapping.png differ diff --git a/Documentation/topics/shared/images/info-bar.png b/Documentation/topics/shared/images/info-bar.png new file mode 100644 index 00000000..f1473c2a Binary files /dev/null and b/Documentation/topics/shared/images/info-bar.png differ diff --git a/Documentation/topics/shared/index.md b/Documentation/topics/shared/index.md index 516efe15..48f16c79 100644 --- a/Documentation/topics/shared/index.md +++ b/Documentation/topics/shared/index.md @@ -19,11 +19,13 @@ The Shared Library is not a product that is sold on its own, but any developer w - An [Avatar](windows-controls/avatar.md) control to represent people or objects. - An [AvatarGroup](windows-controls/avatar-group.md) control that renders multiple [Avatar](windows-controls/avatar.md) controls. - A [Badge](windows-controls/badge.md) control, which can be used to provide contextual information for other elements or can be used stand-alone. +- A [Card](windows-controls/card.md) control to displays visually grouped information for a single subject. - A [CircularProgressBar](windows-controls/circular-progressbar.md) displays a ranged progress value using fluent animations. It is similar to a native linear `ProgressBar`, except that it renders the progress in a ring shape. - A [CircularThumb](xref:@ActiproUIRoot.Controls.Primitives.CircularThumb) control, which is a thumb gripper with a circular shape and arrow adornment. - A [CustomDrawElement](windows-controls/customdrawelement.md) element, which is an element that raises an event when it is being rendered, allowing for custom drawing. - A [DropShadowChrome](windows-controls/dropshadowchrome.md) decorator, which can be used to render a drop shadow for a popup. - A [HorizontalListBox](windows-controls/horizontallistbox.md) control, which allows for selection of items that are arranged horizontally with a uniform width. +- An [InfoBar](windows-controls/info-bar.md) control, which can be used to display essential information to a user without disrupting the user flow. - A [PixelSnapper](windows-controls/pixelsnapper.md) decorator, which helps prevent image and border blurring in WPF. - A [PopupButton](windows-controls/popupbutton.md) control, which provides an implementation of a popup and split button that can display context menu popups or a popup containing any other WPF content. - A [RadialSlider](windows-controls/radialslider.md) controls, which is a circular slider that can be used to input any scalar value. diff --git a/Documentation/topics/shared/windows-controls/advancedtextblock.md b/Documentation/topics/shared/windows-controls/advancedtextblock.md index 6faa2611..ed313e2a 100644 --- a/Documentation/topics/shared/windows-controls/advancedtextblock.md +++ b/Documentation/topics/shared/windows-controls/advancedtextblock.md @@ -1,7 +1,7 @@ --- title: "AdvancedTextBlock" page-title: "AdvancedTextBlock - Shared Library Controls" -order: 3 +order: 5 --- # AdvancedTextBlock diff --git a/Documentation/topics/shared/windows-controls/animatedexpander.md b/Documentation/topics/shared/windows-controls/animatedexpander.md index 4447c433..fab75caa 100644 --- a/Documentation/topics/shared/windows-controls/animatedexpander.md +++ b/Documentation/topics/shared/windows-controls/animatedexpander.md @@ -1,7 +1,7 @@ --- title: "AnimatedExpander" page-title: "AnimatedExpander - Shared Library Controls" -order: 4 +order: 10 --- # AnimatedExpander diff --git a/Documentation/topics/shared/windows-controls/animatedprogressbar.md b/Documentation/topics/shared/windows-controls/animatedprogressbar.md index f48f44b8..cbf10b3f 100644 --- a/Documentation/topics/shared/windows-controls/animatedprogressbar.md +++ b/Documentation/topics/shared/windows-controls/animatedprogressbar.md @@ -1,7 +1,7 @@ --- title: "AnimatedProgressBar" page-title: "AnimatedProgressBar - Shared Library Controls" -order: 7 +order: 15 --- # AnimatedProgressBar diff --git a/Documentation/topics/shared/windows-controls/avatar-group.md b/Documentation/topics/shared/windows-controls/avatar-group.md index 61c3b686..bd6b2df7 100644 --- a/Documentation/topics/shared/windows-controls/avatar-group.md +++ b/Documentation/topics/shared/windows-controls/avatar-group.md @@ -1,7 +1,7 @@ --- title: "AvatarGroup" page-title: "Avatar Group - Shared Library Controls" -order: 9 +order: 21 --- # AvatarGroup diff --git a/Documentation/topics/shared/windows-controls/avatar.md b/Documentation/topics/shared/windows-controls/avatar.md index 1738d29f..3598324a 100644 --- a/Documentation/topics/shared/windows-controls/avatar.md +++ b/Documentation/topics/shared/windows-controls/avatar.md @@ -1,7 +1,7 @@ --- title: "Avatar" page-title: "Avatar - Shared Library Controls" -order: 8 +order: 20 --- # Avatar diff --git a/Documentation/topics/shared/windows-controls/badge.md b/Documentation/topics/shared/windows-controls/badge.md index 835ee4c2..1b31fb4c 100644 --- a/Documentation/topics/shared/windows-controls/badge.md +++ b/Documentation/topics/shared/windows-controls/badge.md @@ -1,7 +1,7 @@ --- title: "Badge" page-title: "Badge - Shared Library Controls" -order: 10 +order: 25 --- # Badge diff --git a/Documentation/topics/shared/windows-controls/card.md b/Documentation/topics/shared/windows-controls/card.md new file mode 100644 index 00000000..5eeff37d --- /dev/null +++ b/Documentation/topics/shared/windows-controls/card.md @@ -0,0 +1,387 @@ +--- +title: "Card" +page-title: "Card - Fundamentals Controls" +order: 30 +--- +# Card + +The [Card](xref:@ActiproUIRoot.Controls.Card) control is typically used to present visually grouped information for a single subject. + +![Screenshot](../images/card.png) + +*Card control with optional cover, footer, thumbnail, and default header* + +## Content Areas + +The [Card](xref:@ActiproUIRoot.Controls.Card) control is defined by multiple content areas: +- `Content` (Body) - The default content area of the card. +- [Cover](xref:@ActiproUIRoot.Controls.Card.Cover) - Typically used for a high-quality image which can be docked to any side of the card. +- [Header](xref:@ActiproUIRoot.Controls.Card.Header) - Displayed above the content, and typically contains a title and/or description. +- [Thumbnail](xref:@ActiproUIRoot.Controls.Card.Thumbnail) - Typically a small image or icon displayed on the left side of the header. +- [Footer](xref:@ActiproUIRoot.Controls.Card.Footer) - Displayed at the bottom of the card. + +Each content area can optionally be set to any value supported by `ContentPresenter` and the layout will adjust to only show the areas where content is defined. + +> [!TIP] +> In some scenarios, content may not be automatically detected. For instance, if a `DataTemplate` is used to define content without setting the corresponding content property, the card will not know that content is available. Use the [IsCoverVisible](xref:@ActiproUIRoot.Controls.Card.IsCoverVisible), [IsHeaderVisible](xref:@ActiproUIRoot.Controls.Card.IsHeaderVisible), [IsThumbnailVisible](xref:@ActiproUIRoot.Controls.Card.IsThumbnailVisible), and [IsFooterVisible](xref:@ActiproUIRoot.Controls.Card.IsFooterVisible) properties to manually control the visibility of each content area. + +### Content (Body) + +[Card](xref:@ActiproUIRoot.Controls.Card) is a `ContentControl`, and the default content of the control will be displayed in the body area of the card. The content can be set to any value supported by `ContentPresenter`. + +The following example demonstrates defining the content of a [Card](xref:@ActiproUIRoot.Controls.Card): + +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + +``` +} +@if (wpf) { +```xaml +xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared" +... + + + +``` +} + +### Cover + +The [Cover](xref:@ActiproUIRoot.Controls.Card.Cover) can be docked to any side of the card using the [CoverDock](xref:@ActiproUIRoot.Controls.Card.CoverDock) property. While a high-quality image is typically used for the [Cover](xref:@ActiproUIRoot.Controls.Card.Cover), it can be set to any value supported by `ContentPresenter`. + +@if (wpf) { +> [!TIP] +> The [CoverTemplateSelector](xref:@ActiproUIRoot.Controls.Card.CoverTemplateSelector) is pre-configured with a default [ImageTemplateSelector](xref:@ActiproUIRoot.Controls.ImageTemplateSelector), so it supports `ImageSource` and `Geometry` data values. See the [Template Selectors](template-selectors.md) topic for more details. +} + +The following example demonstrates creating a [Card](xref:@ActiproUIRoot.Controls.Card) with a cover image docked to the left: + +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + +``` +} +@if (wpf) { +```xaml +xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared" +... + + + + + + + + + +``` +} + +### Header + +The [Title](xref:@ActiproUIRoot.Controls.Card.Title) and [Description](xref:@ActiproUIRoot.Controls.Card.Description) properties can be used to define a header with a default template where the [Title](xref:@ActiproUIRoot.Controls.Card.Title) is displayed with typography consistent with a heading, and the [Description](xref:@ActiproUIRoot.Controls.Card.Description), if defined, is displayed immediately below it. + +@if (avalonia) { +Use the [TitleTheme](xref:@ActiproUIRoot.Controls.Card.TitleTheme) and [DescriptionTheme](xref:@ActiproUIRoot.Controls.Card.DescriptionTheme) properties to customize the appearance of each element. +} +@if (wpf) { +Use the [TitleStyle](xref:@ActiproUIRoot.Controls.Card.TitleStyle) and [DescriptionStyle](xref:@ActiproUIRoot.Controls.Card.DescriptionStyle) properties to customize the appearance of each element. +} + +The following example demonstrates creating a [Card](xref:@ActiproUIRoot.Controls.Card) with both [Title](xref:@ActiproUIRoot.Controls.Card.Title) and [Description](xref:@ActiproUIRoot.Controls.Card.Description) defined: + +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + +``` +} +@if (wpf) { +```xaml +xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared" +... + + + +``` +} + +Alternatively, the [Header](xref:@ActiproUIRoot.Controls.Card.Header) can be set to any value supported by `ContentPresenter`. In this case, the explicit content will be used instead of the default template based on the [Title](xref:@ActiproUIRoot.Controls.Card.Title) and [Description](xref:@ActiproUIRoot.Controls.Card.Description) properties. + +The following example demonstrates creating a [Card](xref:@ActiproUIRoot.Controls.Card) with an explicit [Header](xref:@ActiproUIRoot.Controls.Card.Header) defined: + +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + Title Here + + + + + +``` +} +@if (wpf) { +```xaml +xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared" +... + + + + Title Here + + + + + +``` +} + +### Thumbnail + +The [Thumbnail](xref:@ActiproUIRoot.Controls.Card.Thumbnail) is displayed in the header area, but is separate from the [Header](xref:@ActiproUIRoot.Controls.Card.Header) content. [Thumbnail](xref:@ActiproUIRoot.Controls.Card.Thumbnail) can be set to any value supported by `ContentPresenter` but is typically used to display a small image. + +@if (wpf) { +> [!TIP] +> The [ThumbnailTemplateSelector](xref:@ActiproUIRoot.Controls.Card.ThumbnailTemplateSelector) is pre-configured with a default [ImageTemplateSelector](xref:@ActiproUIRoot.Controls.ImageTemplateSelector), so it supports `ImageSource` and `Geometry` data values. See the [Template Selectors](template-selectors.md) topic for more details. +} + +By default, the [Thumbnail](xref:@ActiproUIRoot.Controls.Card.Thumbnail) is vertically centered with a right margin to separate it from the [Header](xref:@ActiproUIRoot.Controls.Card.Header). Use the @if (avalonia) {[ThumbnailTheme](xref:@ActiproUIRoot.Controls.Card.ThumbnailTheme)}@if (wpf) {[ThumbnailStyle](xref:@ActiproUIRoot.Controls.Card.ThumbnailStyle)} property to customize the appearance. + +The following example demonstrates creating a [Card](xref:@ActiproUIRoot.Controls.Card) with top-aligned image and a custom margin: + +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + + + + + + + +``` +} +@if (wpf) { +```xaml +xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared" +... + + + + + + + + + + + + + +``` +} + +### Footer + +The [Footer](xref:@ActiproUIRoot.Controls.Card.Footer) can be set to any value supported by `ContentPresenter`. + +The following example demonstrates creating a [Card](xref:@ActiproUIRoot.Controls.Card) with italicized text in the footer: + +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + +``` +} +@if (wpf) { +```xaml +xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared" +... + + + + + + + + + +``` +} + +## Appearance + +The appearance of the control can be fully customized. + +### Brushes + +The following brush properties are available: + +| Property | Description | +| ----- | ----- | +| `Foreground` | The default foreground for all areas. | +| `Background` | The default background for all areas. | +| `BorderBrush` | The brush for the outer border. | +| [HeaderForeground](xref:@ActiproUIRoot.Controls.Card.HeaderForeground) | The foreground for the header area, overriding the default foreground. | +| [HeaderBackground](xref:@ActiproUIRoot.Controls.Card.HeaderBackground) | The background for the header area, overriding the default background. | +| [HeaderBorderBrush](xref:@ActiproUIRoot.Controls.Card.HeaderBorderBrush) | The brush for the bottom border of the header. +| [FooterForeground](xref:@ActiproUIRoot.Controls.Card.FooterForeground) | The foreground for the footer area, overriding the default foreground. | +| [FooterBackground](xref:@ActiproUIRoot.Controls.Card.FooterBackground) | The background for the footer area, overriding the default background. | +| [FooterBorderBrush](xref:@ActiproUIRoot.Controls.Card.FooterBorderBrush) | The brush for the top border of the footer. | + +### Header and Footer Borders + +Use the [HeaderBorderThickness](xref:@ActiproUIRoot.Controls.Card.HeaderBorderThickness) and [FooterBorderThickness](xref:@ActiproUIRoot.Controls.Card.FooterBorderThickness) properties to insert a border below the header or above the footer. In the event header and footer both define a border when no content is defined between them, only the header border will be displayed. + +> [!IMPORTANT] +> When setting the border thickness, only `Thickness.Bottom` is used by the header and `Thickness.Top` is used by the footer. + +### Padding + +![Screenshot](../images/card-padding.png) + +*Card controls with the same padding shown with and without separation between then content and the header/footer* + +By default, the `Padding` is consistently applied around the header, content, and footer areas instead of having separate values for each area. When there is visual separation between the content and the header/footer (either by a border or an explicit background color), the padding will be consistently applied to both sides of the separation. + +> [!NOTE] +> The [Cover](xref:@ActiproUIRoot.Controls.Card.Cover) area does not have any default padding applied so the content can be displayed edge-to-edge. + +## Using Card as a Button + +[Card](xref:@ActiproUIRoot.Controls.Card) derives from `Button`, so it supports the same `Command` model and `Click` event as `Button`. Unlike a `Button`, though, not all instances of [Card](xref:@ActiproUIRoot.Controls.Card) will be interactive and the control has been configured to appear non-interactive by default. + +Set the [IsClickEnabled](xref:@ActiproUIRoot.Controls.Card.IsClickEnabled) property to `true` to enable clicking the card. The `Click` event will not be raised if this property is `false`. + +> [!TIP] +> If the `Command` property is assigned a non-`null` value, the [IsClickEnabled](xref:@ActiproUIRoot.Controls.Card.IsClickEnabled) property is automatically coerced to `true`, so no additional configuration is necessary. + +> [!NOTE] +> Setting the [IsClickEnabled](xref:@ActiproUIRoot.Controls.Card.IsClickEnabled) property to `true` will also trigger hover effects to emphasize the control is actionable. + +@if (wpf) { +## Badge Adornment + +[Card](xref:@ActiproUIRoot.Controls.Card) includes built-in support for adding a [Badge](badge.md) adornment. Refer to the [Badge](badge.md) documentation for details on working with a badge. + +The following properties are available for configuring the badge, which correspond to attached properties on [BadgeService](xref:@ActiproUIRoot.Controls.BadgeService): + +| Property | Description | +| ----- | ----- | +| [Badge](xref:@ActiproUIRoot.Controls.Card.Badge) | Set to an instance of a [Badge](badge.md). | +| [BadgeHorizontalAlignment](xref:@ActiproUIRoot.Controls.Card.BadgeHorizontalAlignment) | Set to one of the [AdornmentHorizontalAlignment](xref:@ActiproUIRoot.Controls.AdornmentHorizontalAlignment) values to alter the horizontal alignment. (Default = [CenterOnTargetRightEdge](xref:@ActiproUIRoot.Controls.AdornmentHorizontalAlignment.CenterOnTargetRightEdge) ) | +| [BadgeHorizontalOffset](xref:@ActiproUIRoot.Controls.Card.BadgeHorizontalOffset) | An explicit offset to be applied after alignment. Positive values shift to the right while negative values shift to the left. | +| [BadgeVerticalAlignment](xref:@ActiproUIRoot.Controls.Card.BadgeVerticalAlignment) | Set to one of the [AdornmentVerticalAlignment](xref:@ActiproUIRoot.Controls.AdornmentVerticalAlignment) values to alter the vertical alignment. (Default = [CenterOnTargetTopEdge](xref:@ActiproUIRoot.Controls.AdornmentVerticalAlignment.CenterOnTargetTopEdge) ) | +| [BadgeVerticalOffset](xref:@ActiproUIRoot.Controls.Card.BadgeVerticalOffset) | An explicit offset to be applied after alignment. Positive values shift down while negative values shift up. | + +} + + +@if (avalonia) { +## Themes + +![Screenshot](../images/card-themes.png) + +*Card control in the outline, solid, soft, and elevated themes* + +The following control themes are supported: +- [CardBase](xref:@ActiproUIRoot.Themes.ControlThemeKind.CardBase) - Base control theme used by several others. +- [CardElevated](xref:@ActiproUIRoot.Themes.ControlThemeKind.CardElevated) (`theme-elevated`) - Has an elevated appearance with a shadow. +- [CardOutline](xref:@ActiproUIRoot.Themes.ControlThemeKind.CardOutline) (`theme-outline`) - Has an outline appearance. +- [CardSoft](xref:@ActiproUIRoot.Themes.ControlThemeKind.CardSoft) (`theme-soft`) - Has a soft fill appearance. +- [CardSolid](xref:@ActiproUIRoot.Themes.ControlThemeKind.CardSolid) (`theme-solid`) - Has a solid appearance. + + +The following example demonstrates how to define a card using the elevated theme: + +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + +``` + +### Elevated Button Animation + +When used as a `Button` and the elevated theme is applied (`theme-elevated` style class name), an animation is applied when the pointer is over the [Card](xref:@ActiproUIRoot.Controls.Card) that slides the control up while raising the elevation of the shadow. + +Animations are automatically enabled. To turn off animations, set the [IsAnimationEnabled](xref:@ActiproUIRoot.Controls.Card.IsAnimationEnabled) property to `false`. +} +@if (wpf) { +## Elevated Appearance + +By default, the [IsShadowEnabled](xref:@ActiproUIRoot.Controls.Card.IsShadowEnabled) property is set to `true` and gives the [Card](xref:@ActiproUIRoot.Controls.Card) an elevated appearance. + +When also used as a `Button`, an animation is applied when the mouse is over the [Card](xref:@ActiproUIRoot.Controls.Card) that slides the control up while raising the elevation of the shadow. + +Animations are automatically disabled, as appropriate, based on system settings. To manually turn off animations, set the [IsAnimationEnabled](xref:@ActiproUIRoot.Controls.Card.IsAnimationEnabled) property to `false`. +} + +@if (avalonia) { + +## Theme Resources + +The following theme resources are available for customizing the appearance of the control: + +| Theme Resource | Description | +| ----- | ----- | +| [CardBorderThickness](xref:@ActiproUIRoot.Themes.ThemeResourceKind.CardBorderThickness) | The default `BorderThickness`. | +| [CardCornerRadius](xref:@ActiproUIRoot.Themes.ThemeResourceKind.CardCornerRadius) | The default `CornerRadius`. | +| [CardPadding](xref:@ActiproUIRoot.Themes.ThemeResourceKind.CardPadding) | The default `Padding`. | + +} +@if (wpf) { +## Theme Assets + +See the [Theme Reusable Assets](../../themes/reusable-assets.md) topic for more details on using and customizing theme assets. The following reusable assets are used by [SettingsCard](xref:@ActiproUIRoot.Controls.Views.SettingsCard): + +| Asset Resource Key | Description | +|-----|-----| +| [CardBorderNormalThicknessKey](xref:@ActiproUIRoot.Themes.AssetResourceKeys.CardBorderNormalThicknessKey) | The default `BorderThickness`. | +| [CardBorderNormalCornerRadiusKey](xref:@ActiproUIRoot.Themes.AssetResourceKeys.CardBorderNormalCornerRadiusKey) | The default [CornerRadius](xref:@ActiproUIRoot.Controls.Card.CornerRadius). | +| [CardBorderNormalThicknessKey](xref:@ActiproUIRoot.Themes.AssetResourceKeys.CardPaddingNormalThicknessKey) | The default `Padding`. | +} \ No newline at end of file diff --git a/Documentation/topics/shared/windows-controls/circular-progressbar.md b/Documentation/topics/shared/windows-controls/circular-progressbar.md index 61b6f646..cdf75aba 100644 --- a/Documentation/topics/shared/windows-controls/circular-progressbar.md +++ b/Documentation/topics/shared/windows-controls/circular-progressbar.md @@ -1,7 +1,7 @@ --- title: "CircularProgressBar" page-title: "CircularProgressBar- Shared Library Controls" -order: 11 +order: 35 --- # CircularProgressBar diff --git a/Documentation/topics/shared/windows-controls/customdrawelement.md b/Documentation/topics/shared/windows-controls/customdrawelement.md index 8cbf299c..d7d72b7f 100644 --- a/Documentation/topics/shared/windows-controls/customdrawelement.md +++ b/Documentation/topics/shared/windows-controls/customdrawelement.md @@ -1,7 +1,7 @@ --- title: "CustomDrawElement" page-title: "CustomDrawElement - Shared Library Controls" -order: 12 +order: 40 --- # CustomDrawElement diff --git a/Documentation/topics/shared/windows-controls/dropshadowchrome.md b/Documentation/topics/shared/windows-controls/dropshadowchrome.md index 63b16909..a38f814a 100644 --- a/Documentation/topics/shared/windows-controls/dropshadowchrome.md +++ b/Documentation/topics/shared/windows-controls/dropshadowchrome.md @@ -1,7 +1,7 @@ --- title: "DropShadowChrome" page-title: "DropShadowChrome - Shared Library Controls" -order: 13 +order: 45 --- # DropShadowChrome diff --git a/Documentation/topics/shared/windows-controls/dynamicimage.md b/Documentation/topics/shared/windows-controls/dynamicimage.md index c18c85e7..720c2ded 100644 --- a/Documentation/topics/shared/windows-controls/dynamicimage.md +++ b/Documentation/topics/shared/windows-controls/dynamicimage.md @@ -1,7 +1,7 @@ --- title: "DynamicImage" page-title: "DynamicImage - Shared Library Controls" -order: 14 +order: 50 --- # DynamicImage diff --git a/Documentation/topics/shared/windows-controls/editablecontentcontrol.md b/Documentation/topics/shared/windows-controls/editablecontentcontrol.md index 97f823c3..173fea1c 100644 --- a/Documentation/topics/shared/windows-controls/editablecontentcontrol.md +++ b/Documentation/topics/shared/windows-controls/editablecontentcontrol.md @@ -1,7 +1,7 @@ --- title: "EditableContentControl" page-title: "EditableContentControl - Shared Library Controls" -order: 16 +order: 55 --- # EditableContentControl diff --git a/Documentation/topics/shared/windows-controls/horizontallistbox.md b/Documentation/topics/shared/windows-controls/horizontallistbox.md index 6f2dc755..733b76b5 100644 --- a/Documentation/topics/shared/windows-controls/horizontallistbox.md +++ b/Documentation/topics/shared/windows-controls/horizontallistbox.md @@ -1,7 +1,7 @@ --- title: "HorizontalListBox" page-title: "HorizontalListBox - Shared Library Controls" -order: 19 +order: 60 --- # HorizontalListBox diff --git a/Documentation/topics/shared/windows-controls/imagetextinfo.md b/Documentation/topics/shared/windows-controls/imagetextinfo.md index b82e49f8..ace8ffef 100644 --- a/Documentation/topics/shared/windows-controls/imagetextinfo.md +++ b/Documentation/topics/shared/windows-controls/imagetextinfo.md @@ -1,7 +1,7 @@ --- title: "ImageTextInfo" page-title: "ImageTextInfo - Shared Library Controls" -order: 21 +order: 65 --- # ImageTextInfo diff --git a/Documentation/topics/shared/windows-controls/index.md b/Documentation/topics/shared/windows-controls/index.md index dbf4394e..6caac15b 100644 --- a/Documentation/topics/shared/windows-controls/index.md +++ b/Documentation/topics/shared/windows-controls/index.md @@ -31,6 +31,10 @@ The [AvatarGroup](avatar-group.md) control renders multiple [Avatar](avatar.md) The [Badge](badge.md) control is used to provide contextual information for other elements or can be used stand-alone. +## The Card Control + +The [Card](card.md) control is typically used to present visually grouped information for a single subject. + ## The CircularProgressBar Control [CircularProgressBar](circular-progressbar.md) displays a ranged progress value using fluent animations. It is similar to a native linear `ProgressBar`, except that it renders the progress in a ring shape. @@ -65,6 +69,10 @@ The [HorizontalListBox](horizontallistbox.md) control is a restyled native `List The [ImageTextInfo](imagetextinfo.md) class is a simple helper class that can be used to store image and text data for databinding. +## The InfoBar Control + +The [InfoBar](info-bar.md) control can be used to display essential information to a user without disrupting the user flow. + ## The PixelSnapper Decorator The [PixelSnapper](pixelsnapper.md) decorator snaps the measurement of its child content to integer values, thereby helping to prevent blurry images and borders that may appear after it. diff --git a/Documentation/topics/shared/windows-controls/info-bar.md b/Documentation/topics/shared/windows-controls/info-bar.md new file mode 100644 index 00000000..277d8d45 --- /dev/null +++ b/Documentation/topics/shared/windows-controls/info-bar.md @@ -0,0 +1,262 @@ +--- +title: "InfoBar" +page-title: "InfoBar - Shared Library Controls" +order: 67 +--- +# InfoBar + +An [InfoBar](xref:@ActiproUIRoot.Controls.InfoBar) can be used to display essential information to a user without disrupting the user flow. + +![Screenshot](../images/info-bar.png) + +*InfoBar with default severity showing a title and message* + +## Title and Message + +The [Title](xref:@ActiproUIRoot.Controls.InfoBar.Title) property is typically set to short text that categorizes the message being displayed while the [Message](xref:@ActiproUIRoot.Controls.InfoBar.Message) property is set to text that provides additional detail. + +The following demonstrates how to create an info bar with a title and message: + +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + +``` +} +@if (wpf) { +```xaml +xmlns:shared="http://schemas.actiprosoftware.com/winfx/xaml/shared" +... + +``` +} + +## Severity + +![Screenshot](../images/info-bar-severity.png) + +*InfoBar with Information, Success, Warning, and Error severities* + +By default, an [InfoBar](xref:@ActiproUIRoot.Controls.InfoBar) is displayed with [Information](xref:@ActiproUIRoot.Controls.InfoBarSeverity.Information) severity, but the [Severity](xref:@ActiproUIRoot.Controls.InfoBar.Severity) property can be set to any one of the [InfoBarSeverity](xref:@ActiproUIRoot.Controls.InfoBarSeverity) values. Each severity automatically applies a default[Icon](xref:@ActiproUIRoot.Controls.InfoBar.Icon) and `Background` brush to visually distinguish one severity from another. + +## Action + +![Screenshot](../images/info-bar-action.png) + +*InfoBar with action button* + +The [Action](xref:@ActiproUIRoot.Controls.InfoBar.Action) can be set to any value supported by `ContentPresenter`, but is typically used to show a button or hyperlink the user can act upon to respond to the message. + +The following demonstrates how to create an info bar with a button for an action: + +@if (avalonia) { +```xaml +xmlns:actipro="http://schemas.actiprosoftware.com/avaloniaui" +... + + + + + + + + + + Actipro Ribbon includes a built-in footer for displaying additional content below the Ribbon. The footer + can be set to any content and is great for tips or notifications. + + This sample has been configured with an InfoBar that allows for the configuration of multiple severity + levels, pre-defined or custom images, optional actions/content, and a close button. + + Click the 'Close' button on the InfoBar to hide the MVVM or XAML sample footer. Use the corresponding + 'Show Footer' button to re-display the footer. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/OptionsViewModel.cs b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/OptionsViewModel.cs new file mode 100644 index 00000000..f3061bb7 --- /dev/null +++ b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/OptionsViewModel.cs @@ -0,0 +1,93 @@ +using ActiproSoftware.Windows; +using ActiproSoftware.Windows.Controls; +using ActiproSoftware.Windows.Controls.Bars; +using System.ComponentModel; +using System.Windows; +using System.Windows.Input; + +namespace ActiproSoftware.ProductSamples.BarsSamples.QuickStart.FooterInfoBar { + + /// + /// Defines configurable options for this sample. + /// + public class OptionsViewModel : ObservableObjectBase { + + private bool canClose = true; + private bool isIconVisible = true; + private Thickness padding = new Thickness(10, 5, 10, 5); + private RibbonQuickAccessToolBarLocation qatLocation = RibbonQuickAccessToolBarLocation.Below; + private InfoBarSeverity severity = InfoBarSeverity.Success; + private ICommand showFooterMvvmCommand; + private ICommand showFooterXamlCommand; + + ///////////////////////////////////////////////////////////////////////////////////////////////////// + // PUBLIC PROCEDURES + ///////////////////////////////////////////////////////////////////////////////////////////////////// + + /// + /// Gets or sets if the info bar can be closed. + /// + /// true if the info bar can be closed; otherwise false. + public bool CanClose { + get => canClose; + set => SetProperty(ref canClose, value); + } + + /// + /// Gets or sets if the info bar icon is visible. + /// + /// true if the info bar icon is visible; otherwise false. + public bool IsIconVisible { + get => isIconVisible; + set => SetProperty(ref isIconVisible, value); + } + + /// + /// Gets or sets the padding for the info bar. + /// + /// A value. + public Thickness Padding { + get => padding; + set => SetProperty(ref padding, value); + } + + /// + /// Gets or sets the location of the Quick Access Toolbar. + /// + /// One of the values. + [DisplayName("QAT location")] + public RibbonQuickAccessToolBarLocation QuickAccessToolBarLocation { + get => qatLocation; + set => SetProperty(ref qatLocation, value); + } + + /// + /// Gets of sets the severity of the info bar. + /// + /// One of the values. + public InfoBarSeverity Severity { + get => severity; + set => SetProperty(ref severity, value); + } + + /// + /// Gets or sets the command that will be executed to show the MVVM-based footer. + /// + /// An . + public ICommand ShowFooterMvvmCommand { + get => showFooterMvvmCommand; + set => SetProperty(ref showFooterMvvmCommand, value); + } + + /// + /// Gets or sets the command that will be executed to show the XAML-based footer. + /// + /// An . + public ICommand ShowFooterXamlCommand { + get => showFooterXamlCommand; + set => SetProperty(ref showFooterXamlCommand, value); + } + + } + +} diff --git a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/SampleControlBase.cs b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/SampleControlBase.cs new file mode 100644 index 00000000..0f4275cf --- /dev/null +++ b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/SampleControlBase.cs @@ -0,0 +1,115 @@ +using ActiproSoftware.ProductSamples.BarsSamples.Common; +using ActiproSoftware.Windows.Controls.Bars.Mvvm; +using System.ComponentModel; +using System.Windows; +using System.Windows.Controls; + +namespace ActiproSoftware.ProductSamples.BarsSamples.QuickStart.FooterInfoBar { + + /// + /// Provides the base user control of shared logic for this sample that is extended for MVVM- and XAML-based samples. + /// + public abstract class SampleControlBase : UserControl { + + #region Dependency Properties + + public static readonly DependencyProperty OptionsProperty = DependencyProperty.Register(nameof(Options), typeof(OptionsViewModel), typeof(SampleControlBase), new PropertyMetadata(null, OnOptionsPropertyValueChanged)); + + #endregion Dependency Properties + + ///////////////////////////////////////////////////////////////////////////////////////////////////// + // OBJECT + ///////////////////////////////////////////////////////////////////////////////////////////////////// + + /// + /// Initializes a new instance of the class. + /// + public SampleControlBase() { + // Initialize the Ribbon view models (used by both XAML and MVVM samples for the Ribbon configuration not related to the footer) + this.Ribbon = InitializeRibbonViewModels(); + } + + ///////////////////////////////////////////////////////////////////////////////////////////////////// + // NON-PUBLIC PROCEDURES + ///////////////////////////////////////////////////////////////////////////////////////////////////// + + /// + /// Occurs when the dependency property value has changed. + /// + /// The sender of the event. + /// The containing data related to this event. + private static void OnOptionsPropertyValueChanged(DependencyObject obj, DependencyPropertyChangedEventArgs e) + => ((SampleControlBase)obj).OnOptionsPropertyValueChanged(e.OldValue as OptionsViewModel, e.NewValue as OptionsViewModel); + + ///////////////////////////////////////////////////////////////////////////////////////////////////// + // PUBLIC PROCEDURES + ///////////////////////////////////////////////////////////////////////////////////////////////////// + + /// + /// Initializes the view models for ribbon. + /// + /// A new . + protected virtual RibbonViewModel InitializeRibbonViewModels() { + // The focus of this sample is the Ribbon Footer, so base the MVVM- and XAML-based samples + // will reuse the same core Ribbon MVVM configuration for non-footer configuration to keep + // sample focused only on the footer configuration + var ribbonViewModel = SampleViewModelFactory.CreateDefaultRichTextEditorRibbonWindowViewModel().Ribbon; + ribbonViewModel.IsApplicationButtonVisible = false; + ribbonViewModel.IsCollapsible = false; + return ribbonViewModel; + } + + /// + /// Handles a change in one of the individual property values on . + /// + /// The sender of the event. + /// The event data. + protected virtual void OnOptionsPropertyChanged(object sender, PropertyChangedEventArgs args) { + if (Ribbon == null) + return; + + // Synchronize the footer with current options + UpdateFooter(); + } + + /// + /// Handles a change in the dependency property value. + /// + /// The old value. + /// The new value. + protected virtual void OnOptionsPropertyValueChanged(OptionsViewModel oldValue, OptionsViewModel newValue) { + // Stop listening for changes + if (oldValue != null) + oldValue.PropertyChanged -= OnOptionsPropertyChanged; + + // Listen for changes + if (newValue != null) + newValue.PropertyChanged += OnOptionsPropertyChanged; + + // Synchronize the footer with current options + UpdateFooter(); + + } + + /// + /// Gets or sets the options associated with this control. + /// + public OptionsViewModel Options { + get => (OptionsViewModel)GetValue(OptionsProperty); + set => SetValue(OptionsProperty, value); + } + + /// + /// Gets the view model for the Ribbon control. + /// + /// A . + public RibbonViewModel Ribbon { get; private set; } + + /// + /// Updates the footer based on the current sample options. + /// + protected virtual void UpdateFooter() { /* no op */ } + + } + +} diff --git a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/SampleMvvmControl.xaml b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/SampleMvvmControl.xaml new file mode 100644 index 00000000..2a37be44 --- /dev/null +++ b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/SampleMvvmControl.xaml @@ -0,0 +1,28 @@ + + + + + + + + + + + + + + + + + diff --git a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/SampleMvvmControl.xaml.cs b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/SampleMvvmControl.xaml.cs new file mode 100644 index 00000000..9920d953 --- /dev/null +++ b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/SampleMvvmControl.xaml.cs @@ -0,0 +1,108 @@ +using ActiproSoftware.Windows.Controls.Bars.Mvvm; +using ActiproSoftware.Windows.Input; +using System.Windows; + +namespace ActiproSoftware.ProductSamples.BarsSamples.QuickStart.FooterInfoBar { + + /// + /// Provides the user control for this sample that uses an MVVM-based ribbon configuration. + /// + public partial class SampleMvvmControl : SampleControlBase { + + private RibbonFooterViewModel footerViewModel; + + ///////////////////////////////////////////////////////////////////////////////////////////////////// + // OBJECT + ///////////////////////////////////////////////////////////////////////////////////////////////////// + + /// + /// Initializes a new instance of the class. + /// + public SampleMvvmControl() { + InitializeComponent(); + + // Configure this code-behind to be the view model for this sample + this.DataContext = this; + } + + ///////////////////////////////////////////////////////////////////////////////////////////////////// + // NON-PUBLIC PROCEDURES + ///////////////////////////////////////////////////////////////////////////////////////////////////// + + /// + /// Gets the view model for the footer. + /// + /// A value. + private RibbonFooterViewModel FooterViewModel { + get { + if (footerViewModel is null) { + footerViewModel = new RibbonFooterViewModel() { + + // The RibbonFooterInfoBarContentViewModel can be used to define a footer + // with features supported by the InfoBar control + Content = new RibbonFooterInfoBarContentViewModel() { + CanClose = Options?.CanClose ?? true, + IsIconVisible = Options?.CanClose ?? true, + Message = "Use an info bar for essential app messages", + Padding = Options?.Padding ?? new Thickness(), + Title = "InfoBar", + Severity = Options?.Severity ?? Windows.Controls.InfoBarSeverity.Information, + }, + + // Footer must not have padding so InfoBar can display edge-to-edge + Padding = new Thickness(), + }; + } + return footerViewModel; + } + } + + /// + /// Shows the footer. + /// + private void ShowFooter() { + // When the footer is closed the view model is cleared. Show the footer again + // by re-assigning the view model that defines the footer + Ribbon.Footer = this.FooterViewModel; + } + + ///////////////////////////////////////////////////////////////////////////////////////////////////// + // PUBLIC PROCEDURES + ///////////////////////////////////////////////////////////////////////////////////////////////////// + + /// + protected override RibbonViewModel InitializeRibbonViewModels() { + var ribbonViewModel = base.InitializeRibbonViewModels(); + + // Initialize the ribbon with a footer already displayed + ribbonViewModel.Footer = this.FooterViewModel; + + return ribbonViewModel; + } + + /// + protected override void OnOptionsPropertyValueChanged(OptionsViewModel oldValue, OptionsViewModel newValue) { + // Configure the command to show the MVVM-based footer + if (newValue is not null) + newValue.ShowFooterMvvmCommand = new DelegateCommand(_ => ShowFooter()); + + base.OnOptionsPropertyValueChanged(oldValue, newValue); + } + + /// + protected override void UpdateFooter() { + if (Options == null) + return; + + // Update properties to match the sample options + if (FooterViewModel?.Content is RibbonFooterInfoBarContentViewModel infoBarViewModel) { + infoBarViewModel.CanClose = Options.CanClose; + infoBarViewModel.IsIconVisible = Options.IsIconVisible; + infoBarViewModel.Padding = Options.Padding; + infoBarViewModel.Severity = Options.Severity; + } + } + + } + +} diff --git a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/SampleXamlControl.xaml b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/SampleXamlControl.xaml new file mode 100644 index 00000000..836a0966 --- /dev/null +++ b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/SampleXamlControl.xaml @@ -0,0 +1,74 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/SampleXamlControl.xaml.cs b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/SampleXamlControl.xaml.cs new file mode 100644 index 00000000..5b41066c --- /dev/null +++ b/Samples/SampleBrowser/ProductSamples/BarsSamples/QuickStart/FooterInfoBar/SampleXamlControl.xaml.cs @@ -0,0 +1,61 @@ +using ActiproSoftware.Windows.Input; +using System; + +namespace ActiproSoftware.ProductSamples.BarsSamples.QuickStart.FooterInfoBar { + + /// + /// Provides the user control for this sample that uses a XAML-based ribbon configuration. + /// + public partial class SampleXamlControl : SampleControlBase { + + ///////////////////////////////////////////////////////////////////////////////////////////////////// + // OBJECT + ///////////////////////////////////////////////////////////////////////////////////////////////////// + + /// + /// Initializes a new instance of the class. + /// + public SampleXamlControl() { + InitializeComponent(); + + // Configure this code-behind to be the view model for this sample + this.DataContext = this; + + // IMPORTANT: This sample uses a RibbonViewModel to help pre-populate the ribbon controls, + // and this will, by default, bind Ribbon.ClearFooterCommand to the RibbonViewModel.ClearFooterCommand. + // Since this sample is not using MVVM footers, restore the default XAML-friendly command logic by setting + // Ribbon.ClearFooterCommand to null. + // + // This step is ONLY necessary if RibbonViewModel is used and the the Ribbon.Footer is defined in XAML. + this.Dispatcher.BeginInvoke((Action)(() => ribbon.ClearFooterCommand = null), System.Windows.Threading.DispatcherPriority.Input); + } + + ///////////////////////////////////////////////////////////////////////////////////////////////////// + // NON-PUBLIC PROCEDURES + ///////////////////////////////////////////////////////////////////////////////////////////////////// + + /// + /// Shows the footer. + /// + private void ShowFooter() { + // When the footer is closed the FooterContent is cleared. Show the footer again + // by re-assigning the original RibbonFooterControl to the FooterContent + ribbon.FooterContent = footer; + } + + ///////////////////////////////////////////////////////////////////////////////////////////////////// + // PUBLIC PROCEDURES + ///////////////////////////////////////////////////////////////////////////////////////////////////// + + /// + protected override void OnOptionsPropertyValueChanged(OptionsViewModel oldValue, OptionsViewModel newValue) { + // Configure the command to show the MVVM-based footer + if (newValue is not null) + newValue.ShowFooterXamlCommand = new DelegateCommand(_ => ShowFooter()); + + base.OnOptionsPropertyValueChanged(oldValue, newValue); + } + + } + +} diff --git a/Samples/SampleBrowser/ProductSamples/EditorsSamples/Common/EnumWithoutFlags.cs b/Samples/SampleBrowser/ProductSamples/EditorsSamples/Common/EnumWithoutFlags.cs index 5f62225b..f32d134c 100644 --- a/Samples/SampleBrowser/ProductSamples/EditorsSamples/Common/EnumWithoutFlags.cs +++ b/Samples/SampleBrowser/ProductSamples/EditorsSamples/Common/EnumWithoutFlags.cs @@ -1,5 +1,6 @@ using System; using System.ComponentModel; +using System.ComponentModel.DataAnnotations; namespace ActiproSoftware.ProductSamples.EditorsSamples.Common { @@ -11,43 +12,43 @@ public enum EnumWithoutFlags { /// /// Indicates no value. /// - [Description("Nada")] + [Display(Order = 0, Name = "Nada")] None = 0, /// /// Indicates the value 1. /// - [Description("Uno")] + [Display(Order = 1, Name = "Uno")] One = 0x01, /// /// Indicates the value 2. /// - [Description("One and One")] + [Display(Order = 2, Name = "One and One")] Two = 0x02, /// /// Indicates the value 4. /// - [Description("Square root of 16")] + [Display(Order = 4, Name = "Square root of 16")] Four = 0x04, /// /// Indicates the value 8. /// - [Description("2 to the power of 3")] + [Display(Order = 8, Name = "2 to the power of 3")] Eight = 0x08, /// /// Indicates the union of One and Two. /// - [Description("An odd number")] + [Display(Order = 3, Name = "An odd number")] Three = One | Two, /// /// Indicates the union of One, Two, Four, and Eight. /// - [Description("Everything")] + [Display(Name = "Everything")] All = One | Two | Four | Eight } diff --git a/Samples/SampleBrowser/ProductSamples/SharedSamples/QuickStart/CardIntro/MainControl.xaml b/Samples/SampleBrowser/ProductSamples/SharedSamples/QuickStart/CardIntro/MainControl.xaml new file mode 100644 index 00000000..b8b62cb3 --- /dev/null +++ b/Samples/SampleBrowser/ProductSamples/SharedSamples/QuickStart/CardIntro/MainControl.xaml @@ -0,0 +1,540 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The Card control is used to group related information for a single subject. + + + Cards can be display-only or actionable like a button. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +