Version

Configuring Selection (xamDiagram)

Topic Overview

Purpose

This topic explains how to enable/disable the selection of multiple diagram items in the xamDiagram™ control and how to perform selection programmatically.

Required background

The following topics are prerequisites to understanding this topic:

Topic Purpose

This topic provides a conceptual overview of the xamDiagram control and its main features and capabilities.

This topic explains how to add the xamDiagram control to a WPF application.

Introduction

Diagram items selection configuration summary

The xamDiagram control provides functionality enabling the programmatic select of diagram items located on its space. There are several types of selection functionality available - single, multiple, and none, which all can be configured through a property setting. By default, multiple diagram items selection is enabled.

It is possible to select a diagram item either by clicking the left mouse button or drawing a selection rectangle holding the left mouse button down while moving the mouse across the diagram space until all desired diagram items fall within the boundaries of the dash-bordered selection rectangle and then releasing the mouse left button. (For more details see Diagram Items Interactions and Usability.)

Selecting diagram items in the context of the diagram control is useful in visually highlighting an item or a group of items (enclosing the item(s) within a dash-bordered rectangle) when rendering and/or configuring it. This could be achieved using either the options pane or via code. Configure the diagram items selection behavior by setting the xamDiagram control’s SelectionMode property to the specific type of selection desired. By default, multiple elements selection is the property default setting (SelectionMode="Multiple").

It is possible to programmatically change the selection state of a diagram item using the property setting ( DiagramItem.IsSelected), implemented separately from the user interaction selection functionality.

xamDiagram Configuring Selection 1.png

The selection of the diagram items populates the SelectedItems collection and fires the SelectionChanged event each time this collection changes, allowing for the application of custom logic to its members such as programmatically adding/removing diagram items, etc. When data binding is used, the SelectedDataItems collection is kept in sync with the SelectedItems and contains the data items corresponding to the selected diagram items.

Diagram items selection configuration summary chart

The following table briefly explains the configurable aspects of diagram items selection and maps them to the properties that configure them.

Configurable aspect Details Properties

Selection mode

The method by which diagram items are selected at a time

Configuring the Selection Mode

Overview

To specify how many diagram items can be included in a selection on the diagram space, configure the control’s selection mode. The default setting enables multiple diagram items selection on the diagram, so to limit the number of items to one, set the value of the SelectionMode property to “Single” ; alternately set it to “None” to disable selection.

Diagram items selection interactions reference chart

The following table summarizes the user interaction capabilities of the xamDiagram control with respect to the SelectionMode property setting.

For the user to… Using… The SelectionMode property must be set to:

Select a single item on the diagram space

  • Mouse click

  • Selection rectangle

“Single”

Select multiple diagram items

  • Pressing and holding Shift/Ctrl + clicking on the element to be included in the selection

  • Selection rectangle

“Multiple”

Clear the entire current selection

Mouse click on the diagram surface outside the selection rectangle

  • “Single”

  • “Multiple”

Include/Exclude specific diagram items to/from multiple selection

Pressing and holding Shift/Ctrl + clicking on the element to be included/excluded

“Multiple”

Property settings

The following table maps the desired configuration to the property settings that manage it.

In order to: Use this property: And set it to:

Configure single item containing selection capability on the diagram space

“Single”

Configure multiple items containing capability on the diagram space

“Multiple”

Disable the selection of items on the diagram space

“None”

Selecting/De-Selecting Items Programmatically

Overview

The xamDiagram control allows you to select and de-select items programmatically. You select or de-select an item by configuring its selection state as determined by the value of the IsSelected property.

Property settings

The following table maps the desired configuration to the property settings that manage it.

In order to: Use this property: And set it to:

Enable the item selection capability of the diagram

“True”

Disable the item selection capability of the diagram

“False”

Example

The screenshot below demonstrates node selection state configuration as a result of the following settings:

Property Value

“True”

xamDiagram Configuring Selection 2.png

Following is the code that implements this example.

In XAML:

<ig:XamDiagram x:Name="diagram"
               Width="300"
               Height="250"
               Background="#F9F9F9">
    <ig:DiagramNode x:Name="node0"
                    Position="5,125"
                    IsSelected=”True”/>
</ig:XamDiagram>

Related Topics

The following topics provide additional information related to this topic.

Topic Purpose

This topic provides a summary of all user interaction tasks in the xamDiagram control.

This topic explains how to use the commands provided by the xamDiagram control and how to change the keyboard shortcuts associated with the commands.