Prerequisite Knowledge Views and Themes: Multi-surface Themes Overview Multi-surface Themes: Surface Configurations

Themes determine the color scheme and default visual cues applied to the elements in a grid and, in the case of multi-surface themes, how and where the regions supported by a surface configuration are displayed. 

Every multi-surface theme identifies the target surface configurations it supports through the TargetSurfaceConfiguration attribute. This attribute must be set on the class and indicates that the theme offers a layout that is compatible with any specified surface configuration(s).

Surface and Region Configurations

At construction (i.e., in the constructor), multi-surface themes determine the default surface configurations that will be applied to a multi-surface view's surfaces by adding the desired configurations to the DefaultSurfaceConfigurations. If a custom theme derives from an existing multi-surface theme (e.g., ElementalBlackTheme), the default surface configurations can be added or removed from the base-filled DefaultSurfaceConfigurations collection (see Table 1 in Elemental Themes and Chameleon Theme for a list of the default surface configurations and their index in the collection).

The default surface configurations can also be overridden by adding surface configurations to a theme's SurfaceConfigurations collection and specifying the surfaces to which they will be applied using the Surfaces attached property defined on the multi-surface view (see Examples 1 and 3 in Surface Configurations).

Through the DefaultDataRegionConfiguration, DefaultTitleRegionConfiguration, and DefaultImageRegionConfiguration properties, a multi-surface theme can define region configurations that will be applied to all regions in all surfaces for which a corresponding region configuration has not been explicitly defined (see Examples 2 and 3 in Surface Configurations).

Row ControlTemplate

Multi-surface themes determine how rows (i.e., cards or card surfaces) are laid out by providing a ControlTemplate that targets Row and row-derived objects (e.g., DataRow) and that contains RegionPresenters whose visibility and positions are determined by surface configurations. Like ContentPresenters, RegionPresenters are included in ControlTemplates to indicate where content (i.e., regions) is to be displayed. As such, through their Content property, the visual tree used to display their data can be provided. 

Within a region presenter, a Panel must be identified as the element in which the cells displayed in the region will be contained by setting the presenter's IsCellsHost attached property to true. If a corresponding region configuration defines a new template but does not include a Panel identified as being a cell host, the names of the fields that were provided through the FieldNames property but were not explicitly positioned in the template will not be displayed in the region.

For detailed information on RegionPresenters and their role in ControlTemplates, refer to the Custom Surface Configurations topic.

Surface-configuration Context

Through a multi-surface view's SurfaceConfigurationContext attached property, the properties exposed by a surface configuration and multi-surface theme (e.g., TitleRegionPosition and GradientLightColor) can be accessed in order to bind elements in the theme-defined ControlTemplates to their values or use them in triggers (see CardflowView3D.Elemental.Pink resource dictionary). 

Examples

Because creating a custom surface configuration and multi-surface theme requires more than a code snippet to demonstrate, links to the required classes are provided below:

1. ImageAndDoubleTitleSurfaceConfiguration Class
   
   Provides the implementation, in code, of a surface configuration that derives from the ImageAndTitleSurfaceConfiguration class and adds a new RegionConfiguration property named "SecondTitleRegionConfiguration". The TargetRegionPresenterName attribute, which specifies the name of the corresponding RegionPresenter in the ControlTemplate ("REGION_SecondTitle"), has also been set on the new property. 
   
   
2. ElementalPinkTheme Class
   
   Provides the implementation, in code, of a theme that derives from the ElementalBlackTheme class and adds a new RegionConfiguration property named "DefaultSecondTitleRegionConfiguration". The TargetRegionPresenterName attribute, which specifies the name of the corresponding RegionPresenter in the ControlTemplate ("REGION_SecondTitle"), has also been set on the new property. 
   
   The TargetSurfaceConfiguration attribute has also been set on the ElementalPinkTheme class to include the ImageAndDoubleTitleSurfaceConfiguration class as a targeted surface configuration.
   
   
3. CardflowView3D.Elemental.Pink.xaml Resource Dictionary
   
   Based on the CardflowView3D.Elemental.Black resource dictionary, this dictionary provides the pink color scheme for the Elemental Pink theme as well as the modified ControlTemplate that contains the second title region identified as "REGION_SecondTitle".
   
   
4. Elemental.Resources.xaml Resource Dictionary
   
   Exact copy of Xceed's Elemental.Resources resource dictionary, which provides the templates and styles required by the CardflowView3D.Elemental.Pink resource dictionary.
   
   
5. generic.xaml Resource Dictionary
   
   The theme-level resource dictionary for the Elemental Pink theme, which must be placed in a themes folder at the root of the project that contains the theme.