Class UserHandle

Represents how to execute commonly or frequently used commands around nodes, connectors, and groups in the diagram.

Inheritance

System.Object

DiagramObject

UserHandle

Implements

IDiagramObject

System.ICloneable

Inherited Members

DiagramObject.GetParent()

DiagramObject.OnPropertyChanged(String, Object, Object, IDiagramObject)

Namespace: Syncfusion.Blazor.Diagram

Assembly: Syncfusion.Blazor.dll

Syntax

public class UserHandle : DiagramObject, IDiagramObject, ICloneable

Remarks

The UserHandle class enables users to create custom interactive handles that can be positioned around diagram elements to perform specific actions such as cloning, deleting, or custom operations through user-defined commands.

Examples

The following example demonstrates how to create and configure a user handle for cloning diagram objects:

DiagramSelectionSettings SelectedModel = new DiagramSelectionSettings();
DiagramObjectCollection<UserHandle> UserHandles = new DiagramObjectCollection<UserHandle>();

protected override void OnInitialized()
{
    // Creating the userhandle for cloning the objects.
    UserHandle cloneHandle = new UserHandle()
    {
        Name = "clone",
        PathData = "M60.3,18H27.5c-3,0-5.5,2.4-5.5,5.5v38.2h5.5V23.5h32.7V18z M68.5,28.9h-30c-3,0-5.5,2.4-5.5,5.5v38.2c0,3,2.4,5.5,5.5,5.5h30c3,0,5.5-2.4,5.5-5.5V34.4C73.9
        ,31.4,71.5,28.9,68.5,28.9z M68.5,72.5h-30V34.4h30V72.5z",
        Visible = true,
        Offset = 0,
        Side = Direction.Bottom,
        Margin = new DiagramThickness() { Top = 0, Bottom = 0, Left = 0, Right = 0 }
    };
    UserHandles = new DiagramObjectCollection<UserHandle>() { cloneHandle };
    SelectedModel = new DiagramSelectionSettings()
    {
        // Enable userhandle for selected model.
        Constraints = SelectorConstraints.UserHandle,
        UserHandles = this.UserHandles
    };
}

Constructors

UserHandle()

Initializes a new instance of the UserHandle.

Declaration

public UserHandle()

UserHandle(UserHandle)

Initializes a new instance of the UserHandle class by copying an existing UserHandle instance.

Declaration

public UserHandle(UserHandle src)

Parameters

Type	Name	Description
UserHandle	src	A UserHandle instance to be copied to initialize the new instance.

Properties

BackgroundColor

Gets or sets the background color of the UserHandle.

Declaration

public string BackgroundColor { get; set; }

Property Value

Type	Description
System.String	A System.String representing the background color of the user handle. The default value is `"black"`.

Remarks

This property affects the visual appearance of the user handle and should be set to ensure proper contrast with the handle's content for accessibility.

Examples

The following example demonstrates how to set the background color of a user handle:

UserHandle = new UserHandle()
{
    Name = "user1",
    ID = "user2",
    BackgroundColor = "red",
};

BorderColor

Gets or sets the border color of the UserHandle.

Declaration

public string BorderColor { get; set; }

Property Value

Type	Description
System.String	A System.String representing the border color of the user handle. The default value is System.String.Empty.

Remarks

The border color property defines the visual appearance of the user handle's border. This property accepts standard CSS color values including hex codes, RGB values, color names, and other valid CSS color formats.

Examples

The following example demonstrates how to set the border color for a user handle:

UserHandle = new UserHandle()
{
    Name = "user1",
    ID = "user2",
    BorderColor = "red",
};

BorderWidth

Gets or sets the border width of the UserHandle.

Declaration

public double BorderWidth { get; set; }

Property Value

Type	Description
System.Double	A System.Double representing the width of the user handle border in pixels. The default value is `0.5`.

Remarks

Setting this value to 0 will remove the border entirely, while larger values create more prominent borders that may improve visibility and user interaction.

Examples

UserHandle = new UserHandle()
{
     Name = "user1",
     ID="user2",
     BorderWidth= 8,
};

Displacement

Gets or sets the displacement (margin) of the UserHandle from its default position. This property is applicable only when the parent is a connector.

Declaration

public double Displacement { get; set; }

Property Value

Type	Description
System.Double	A System.Double representing the distance in pixels by which the user handle is displaced from its default position along the connector. The default value is `10`.

Remarks

This property only affects user handles attached to connectors and has no effect when the user handle is attached to nodes. The displacement is measured in pixels and can be positive or negative values to move the handle in different directions along the connector path.

Examples

The following example demonstrates how to set the displacement for a user handle on a connector:

    UserHandle = new UserHandle()
    {
         Name = "user1",
          ID="user2",
           Displacement= 10,
    };

HorizontalAlignment

Gets or sets the horizontal alignment of the UserHandle.

Declaration

public HorizontalAlignment HorizontalAlignment { get; set; }

Property Value

Type	Description
HorizontalAlignment	A HorizontalAlignment specifying how the user handle is horizontally positioned. The default value is Center.

Remarks

The following alignment options are available:

Stretch - Stretches the user handle throughout its container width
Left - Aligns the user handle to the left side of its container
Right - Aligns the user handle to the right side of its container
Center - Centers the user handle horizontally within its container
Auto - Automatically determines alignment based on the user handle characteristics

Examples

The following example demonstrates how to set the horizontal alignment for a user handle:

UserHandle = new UserHandle()
{
    Name = "user1",
    ID = "user2",
    HorizontalAlignment = HorizontalAlignment.Left,
    Margin = new DiagramThickness() { Top = 0, Bottom = 0, Left = 0, Right = 0 }
};

ID

Gets or sets the unique identifier of the UserHandle.

Declaration

public string ID { get; set; }

Property Value

Type	Description
System.String	A System.String representing the unique identifier for the user handle. The default value is null.

Remarks

The ID property serves as a unique identifier for the user handle within the diagram component.

When working with multiple user handles, ensure each handle has a unique ID to avoid conflicts during interaction and manipulation operations.

Examples

The following example demonstrates how to set the ID property for a user handle:

UserHandle = new UserHandle()
{
    Name = "user1",
    ID = "user2",
};

ImageUrl

Gets or sets the URL of the image associated with the UserHandle. Applicable only if it is an image.

Declaration

public string ImageUrl { get; set; }

Property Value

Type	Description
System.String	A System.String representing the URL of the image. The default value is System.String.Empty.

Remarks

The URL can be an absolute path to an external image resource or a relative path to a local image file. Ensure the image is accessible and properly formatted for optimal display within the diagram component.

Examples

The following example demonstrates how to set the ImageUrl property for a user handle:

UserHandle = new UserHandle()
{
     Name = "user1",
     ID="user2",
     ImageUrl="https://www.w3schools.com/images/w3schools_green.jpg",
};

Margin

Gets or sets the extra space around the outer boundaries of the UserHandle. Applicable only if the parent is a node.

Declaration

public DiagramThickness Margin { get; set; }

Property Value

Type	Description
DiagramThickness	A DiagramThickness representing the margin space around the user handle boundaries. The default value is a DiagramThickness with all sides set to `0`.

Remarks

The margin property defines the additional spacing around the user handle when it is positioned relative to its parent node. This property only takes effect when the user handle is attached to a node element.

Examples

The following example demonstrates how to set margin values for a user handle:

UserHandle = new UserHandle()
{
    Name = "user1",
    ID = "user2",
    Margin = new DiagramThickness() { Top = 0, Bottom = 0, Left = 0, Right = 0 }
};

Name

Gets or sets the name of the UserHandle.

Declaration

public string Name { get; set; }

Property Value

Type	Description
System.String	A System.String representing the name for the user handle. The default value is System.String.Empty.

Remarks

The name property serves as a label or identifier for the user handle within the diagram component.

Examples

The following example demonstrates how to set the name property for a user handle:

UserHandle = new UserHandle()
{
    Name = "user1",
};

Offset

Gets or sets the offset position of the UserHandle relative to its parent element.

Declaration

public double Offset { get; set; }

Property Value

Type	Description
System.Double	A System.Double representing the offset position as a fractional value between 0 and 1. The default value is `0`.

Remarks

The offset determines the position of the user handle along the boundary of its parent node or connector. A value of 0 positions the handle at the start, 0.5 at the center, and 1 at the end of the boundary.

Examples

The following example demonstrates how to set the offset position for a user handle:

UserHandle = new UserHandle()
{
    Name = "user1",
    ID = "user2",
    Offset = 0.3
};

PathColor

Gets or sets the stroke color of the UserHandle.

Declaration

public string PathColor { get; set; }

Property Value

Type	Description
System.String	A System.String representing the stroke color of the user handle shape. The default value is `"white"`.

Remarks

This property defines the outline color of the user handle shape. The color can be specified using standard color names, hexadecimal values, or RGB values.

Examples

This example demonstrates how to set the stroke color of a user handle.

UserHandle = new UserHandle()
{
    Name = "user1",
    ID = "user2",
    PathColor = "brown"
};

PathData

Gets or sets the custom geometry (shape) of the user handle.

Declaration

public string PathData { get; set; }

Property Value

Type	Description
System.String	A System.String representing the SVG path data that defines the custom shape of the user handle. The default value is System.String.Empty.

Remarks

The PathData property allows you to define a custom shape for the user handle using SVG path syntax. This provides flexibility to create handles with unique visual appearances beyond the standard predefined shapes.

Examples

The following example demonstrates how to create a user handle with custom path data:

UserHandle = new UserHandle()
{
    Name = "user1",
    ID = "user2",
    PathData = "M60.3,18H27.5c-3,0-5.5,2.4-5.5,5.5v38.2h5.5V23.5h32.7V18z M68.5,28.9h-30c-3,0-5.5,2.4-5.5,5.5v38.2c0,3,2.4,5.5,5.5,5.5h30c3,0,5.5-2.4,
    5.5-5.5V34.4C73.9,31.4,71.5,28.9,68.5,28.9z M68.5,72.5h-30V34.4h30V72.5z"
};

Side

Gets or sets the position of the UserHandle relative to its parent element.

Declaration

public Direction Side { get; set; }

Property Value

Type	Description
Direction	A Direction value specifying the positioning side of the user handle. The default value is Top.

Remarks

The Side property determines where the user handle appears relative to its parent node or connector. This positioning affects both the visual placement and the interaction behavior of the handle.

Left - Positions the user handle on the left side of the parent element
Right - Positions the user handle on the right side of the parent element
Top - Positions the user handle on the top side of the parent element
Bottom - Positions the user handle on the bottom side of the parent element

Examples

The following example demonstrates how to set the side position for a user handle:

UserHandle = new UserHandle()
{
    Name = "user1",
    ID = "user2",
    BackgroundColor = "red",
    Side = Direction.Bottom,
};

Size

Gets or sets the size of the UserHandle.

Declaration

public double Size { get; set; }

Property Value

Type	Description
System.Double	A System.Double representing the size of the user handle in pixels. The default value is `25`.

Remarks

The size property determines the width and height dimensions of the user handle when rendered in the diagram. The value is specified in pixels and affects both the visual appearance and the interactive area of the handle.

Examples

The following example demonstrates how to set the size property for a user handle:

UserHandle = new UserHandle()
{
    Name = "user1",
    ID = "user2",
    Size = 8,
};

Gets or sets the tooltip configuration for the UserHandle.

Declaration

public DiagramTooltip Tooltip { get; set; }

Property Value

Type	Description
DiagramTooltip	A DiagramTooltip object that defines the tooltip behavior and content for the user handle. The default value is null.

The tooltip provides contextual information when users hover over the user handle. When set to null, no tooltip will be displayed for this handle.

The following example demonstrates creating a user handle with a tooltip in Razor syntax:

UserHandle cloneHandle = new UserHandle
{
    Name = "clone",
    Offset = 0,
    Visible = true,
    VisibleTarget = VisibleTarget.Node,
    Side = Direction.Top,
    Margin = new DiagramThickness { Top = 0, Bottom = 0, Left = 0, Right = 0 },  
    Tooltip = new DiagramTooltip { Content = "NodeTooltip" }
};

VerticalAlignment

Gets or sets the vertical alignment of the UserHandle.

Declaration

public VerticalAlignment VerticalAlignment { get; set; }

Property Value

Type	Description
VerticalAlignment	A VerticalAlignment specifying how the user handle is vertically positioned. The default value is Center.

Remarks

The following vertical alignment options are available:

Stretch - Stretches the user handle throughout the entire vertical space of the container
Top - Aligns the user handle at the top of the container
Bottom - Aligns the user handle at the bottom of the container
Center - Aligns the user handle at the center of the container
Auto - Automatically determines the alignment based on the container characteristics

This property works in conjunction with horizontal alignment to provide precise positioning control for user handles in diagram scenarios.

Examples

The following example demonstrates how to set the vertical alignment for a user handle:

UserHandle = new UserHandle()
{
    Name = "user1",
    ID = "user2",
    VerticalAlignment = VerticalAlignment.Top,
    Margin = new DiagramThickness() { Top = 0, Bottom = 0, Left = 0, Right = 0 }
};

Visible

Gets or sets the visibility of the UserHandle.

Declaration

public bool Visible { get; set; }

Property Value

Type	Description
System.Boolean	A System.Boolean indicating whether the user handle is visible in the diagram. The default value is true.

Remarks

The visibility property controls whether the user handle is displayed and available for user interaction within the diagram component. When set to true, the handle is rendered and can be interacted with by users.

Examples

The following example demonstrates how to configure the visibility of a user handle:

UserHandle = new UserHandle()
{
    Name = "user1",
    ID = "user2",
    Displacement = 10,
    Visible = true  // Handle will be visible and interactive
};

VisibleTarget

Gets or sets the target elements where the UserHandle should be visible.

Declaration

public VisibleTarget VisibleTarget { get; set; }

Property Value

Type	Description
VisibleTarget	A VisibleTarget enumeration specifying which diagram elements can display this user handle. The default value is Node.

Remarks

This property determines whether the user handle appears on nodes, connectors, or rubber band selections. When set to Node, the handle will only be visible when nodes are selected.

Examples

This example demonstrates how to configure a user handle to be visible on different target elements.

UserHandle cloneHandle = new UserHandle()
{
    Name = "clone",
    Offset = 0,
    Visible = true,
    VisibleTarget = VisibleTarget.Node,
    Side = Direction.Top,
    Margin = new DiagramThickness { Top = 0, Bottom = 0, Left = 0, Right = 0 },                          
};

Methods

Clone()

Creates a new user handle that is a copy of the current UserHandle.

Declaration

public override object Clone()

Returns

Type	Description
System.Object	An System.Object that is a copy of this instance of UserHandle.

Overrides

DiagramObject.Clone()

Implements

IDiagramObject

System.ICloneable