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

Surface configurations, which can be applied to any surface exposed by a multi-surface view, support various regions in which data can be displayed. How and where the supported regions are displayed is determined by the multi-surfaces themes.

Understanding Region Presenters

A multi-surface theme determines 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. Each region presenter can be configured through RegionConfiguration properties that are exposed by surface configurations and marked with the TargetRegionPresenterName attribute to identify their corresponding region presenter by their unique, case-sensitive name (see Region Configurations section in Surface Configurations).

The following diagram illustrates the relationships between the ControlTemplate, surface configurations, and region configurations.

1. The ControlTemplate exposes X number of region presenters. For example, in the first image, the layout represents the equivalent of a CompleteSurfaceConfiguration in the Elemental themes.
   
   
2. Surface configurations determine what region presenters in the ControlTemplate they want to display; however, the location of the presenters is determined by the ControlTemplate. In the second image, the TitleSurfaceConfiguration is used, meaning that region-presenters A and C are not displayed and region-presenter B is displayed in the center of the card, as dictated by the ControlTemplate.
   
   
3. Region configurations determine how the content of a region presenter is displayed. In the last image, a RegionConfiguration that explicitly states it will display the LastName and FirstName fields in region-presenter B is provided.

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.

The IsDefaultRegion property identifies 1 region presenter in the ControlTemplate (usually the "data" region presenter) as being the default region in which information from the fields that have not been explicitly assigned to another region (through a region configuration) is displayed. If the IsDefaultRegion property is set on more than one region presenter, the last presenter on which it was set will be used as the default region.

A region presenter's ReadOnly property indicates whether any DataCells that may end up being contained in the region will be editable. By default, image and title region presenters have their ReadOnly property set to true and data region presenters to false. Region presenters also expose the ImageStretchDirection and ImageStretch properties, which determine how images in the region are scaled and stretched, respectively.

Identifying Regions Presenters and Configurations

All of Xceed's multi-surface themes target the 7 base surface configurations (see Table 1 in Surface Configurations) and identify the region presenters in the ControlTemplate using a standardized naming convention similar to that adopted by the WPF framework for template part names (see Table 1).

All region presenters have an associated RegionConfiguration property that is marked with the TargetRegionPresenterName attribute to identify its corresponding region presenter by its unique, case-sensitive name.

Table 1: Region presenter names

By default, if a region configuration does not explicitly state the names of the fields to display or does not provide a new template for its corresponding region presenter, an attempt will be made to automatically extract the fields that will be displayed in each region. If an image field exists in the data source, it will automatically be displayed in the image region (REGION_Image). In the case where more than one image is available, the first one that is found will be used. If no image is found and a surface configuration with an image region is used, a blank "place-holder" will be displayed in the image region. Furthermore, the title region (REGION_Title) will automatically display the value of the main column, and the data region (REGION_Data) will display the remaining fields.

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.