Edit this page

SettingsPane

This article will get you familiar with the SettingsPane control that is part of Telerik Diagramming Framework.

SettingsPane Overview

The SettingsPane control allows the users to examine and modify the settings of the diagramming items in run-time.

In order to use the SettingsPane control along with the RadDiagram in your projects you have to add references to the following assemblies:

  • Telerik.Windows.Controls.Diagrams
  • Telerik.Windows.Diagrams.Core
  • Telerik.Windows.Controls.Diagrams.Extensions
  • Telerik.Windows.Controls
  • Telerik.Windows.Controls.Navigation
  • Telerik.Windows.Controls.Input

The SettingsPane control is a standalone control that can be displayed as the content of any ContentControl. Its main purpose is to provide you with a ready-to-use view that contains the most common features and settings of a single RadDiagramItem (Shape or Connection).

In most Diagramming examples you will find the SettingsPane applied as an AdditionalContent on the diagramming surface. This way the control is displayed next to a focused RadDiagramItem thus allowing users to dynamically change the look and feel of the item. In order to display the SettingsPane this way in your application as well, you can add it through the ItemInformationAdorner.AdditionalContent attached property in the following manner:

<telerik:RadDiagram x:Name="diagram">
    <primitives:ItemInformationAdorner.AdditionalContent>
        <telerik:SettingsPane Diagram="{Binding ElementName=diagram}" />
    </primitives:ItemInformationAdorner.AdditionalContent>
</telerik:RadDiagram>


Where the primitives namespace is defined like this:
xmlns:primitives="clr-namespace:Telerik.Windows.Controls.Diagrams.Primitives;assembly=Telerik.Windows.Controls.Diagrams"

Rad Diagram Settings Pane Overview

Customization

The SettingsPane has a default view that can be used out-of-the-box in scenarios where you only need to display the common settings of a RadDiagramItem. However you can also customize the content of the pane to represent more specific information. These are the basic tasks you might need to implement while customizing your SettingsPane instance:

  • Change the tab headers - in order to change the headers of the tabs in the default SettingsPane, you can change the value of their localization strings. Please take a look at the Localization article to find the localization string of each tab displayed inside the SettingsPane.

  • Add and remove tabs - in order to add or remove tabs from the default SettingsPane, you need to edit the ControlTemplate of the SettingsPaneView as this is the control that represents the content of the SettingsPane. Please take a look at the SettingsPaneView ControlTemplate Structure section for more information.

  • Edit the content of an existing tab - The content of each of the four default SettingsPane tabs – Home, Size, Style, Text, is represented by a different control:

    • SettingsPaneHomeControl - representing the content of the Home tab

    • SettingsPaneSizeControl - representing the content of the Size tab

    • SettingsPaneStyleControl - representing the content of the Style tab

    • SettingsPaneTextControl - representing the content of the Text tab Furthermore, the content of each control is described in its ControlTemplate. This is why in order to change the existing content of a SettingsPane tab, you need to edit the ControlTemplate of the appropriate control.

Furthermore, the content of each control is described in its ControlTemplate. This is why in order to change the existing content of a SettingsPane tab, you need to edit the ControlTemplate of the appropriate control.

Events

RadDiagram exposes two events that come in handy while working with the default SettingsPane:

  • PreviewAdditionalContentActivated - this event is raised by a RadDiagram to inform layouts that the additional content is going to be activated. The event handler receives two arguments:

    • The sender argument contains the RadDiagram This argument is of type object, but can be cast to the RadDiagram type.

    • An AdditionalContentActivatedEventArgs object, that gives you access to a ContextItems collection. This collection of IDiagramItem objects represents the items that have activated the additional content. In most cases it contains a single item - the RadDiagramItem that has activated the SettingsPane.

    Please note that you can handle this event in order to disable the SettingsPane from displaying on certain RadDiagramItems.

  • AdditionalContentActivated - this event is raised by a RadDiagram to inform layouts that the additional content has been activated. The event handler receives two arguments:

    • The sender argument contains the RadDiagram This argument is of type object, but can be cast to the RadDiagram type.

    • An AdditionalContentActivatedEventArgs object, that gives you access to a ContextItems collection. This collection of IDiagramItem objects represents the items that have activated the additional content. In most cases it contains a single item - the RadDiagramItem that has activated the SettingsPane.

SettingsPane ControlTemplate Structure

The SettingsPane ControlTemplate consists of the following elements:

Rad Diagram Settings Pane Templated Structure

  • RootBorder - a Border that represents the main layout control in the SettingsPane

    • [Grid] - a Grid that hosts the SettingsPane ControlTemplate elements

      • [Canvas] - a Canvas that hosts the ToggleButton element

        • ToggleButton - a RadToggleButton control that represents an inactive SettingsPane. Once this button is clicked, the SettingsPaneView gets activated and displayed.
      • Popup - a Popup control that represents the active SettingsPane

        • [Grid] - a Grid panel that hosts the elements of the active SettingsPane

          • [Path] - a Path that represents the callout element of the active SettingsPane

            • DropShadowEffect - a DropShadowEffect
          • [Rectangle] - a Rectangle element

          • [Border] - a Border control wrapping the content of the active SettingsPane

            • SettingsPaneView - a SettingsPaneView control representing the content of the active SettingsPane

SettingsPaneView ControlTemplate Structure

The SettingsPaneView represents the default content of the RadDiagram SettingsPane. This means that if you need to add or remove any tabs from the SettingsPane, you'll have to add or remove them from the SettingsPaneView control. You can examine the SettingsPaneView ControlTemplate structure below:

Rad Diagram Settings Pane View Templated Structure

  • [Border] - a Border control that hosts the content of the SettingsPaneView

    • TabControl - a RadTabControl that represents the content of the SettingsPaneView

      • DropShadowEffect - a DropShadowEffect

      • [RadTabItem] - a RadTabItem control that represents the Home tab in the SettingsPaneView

        • SettingsPaneHomeControl - a SettingsPaneHomeControl that represents the content of the Home tab in the SettingsPaneView
      • [RadTabItem] - a RadTabItem control that represents the Size tab in the SettingsPaneView

        • SettingsPaneSizeControl - a SettingsPaneSizeControl that represents the content of the Size tab in the SettingsPaneView
      • [RadTabItem] - a RadTabItem control that represents the Style tab in the SettingsPaneView

        • SettingsPaneStyleControl - a SettingsPaneStyleControl that represents the content of the Style tab in the SettingsPaneView
      • [RadTabItem] - a RadTabItem control that represents the Text tab in the SettingsPaneView

        • SettingsPaneTextControl - a SettingsPaneTextControl that represents the content of the Text tab in the SettingsPaneView

Please note that the content of each tab is represented by a different control. And Telerik Diagramming Framework comes with a predefined style for each of these controls. This means that in order to modify the content of each tab in a SettingsPane, you need to actually modify the default ControlTemplate of the appropriate control:

  • SettingsPaneHomeControl - representing the content of the Home tab
  • SettingsPaneSizeControl - representing the content of the Size tab
  • SettingsPaneStyleControl - representing the content of the Style tab
  • SettingsPaneTextControl - representing the content of the Text tab