ControlDragger.vb

' ***********************************************************************
' Author   : Elektro
' Modified : 21-November-2015
' ***********************************************************************

#Region " Public Members Summary "

#Region " Constructors "

' New(Control, Opt: Boolean, Opt: Cursor)
' New(IEnumerable(Of Control))

#End Region

#Region " Properties "

' Controls As IEnumerable(Of ControlDragInfo)
' Empty As ControlDragger

#End Region

#Region " Functions "

' FindControlDragInfo(Control) As ControlDragInfo
' FindControlDragInfo(String, Opt: StringComparison) As ControlDragInfo

#End Region

#Region " Methods "

' AddControl(Control, Opt: Boolean, Opt: Cursor)
' AddControls(Control())
' RemoveControl(Control)
' RemoveControls(Control())
' Dispose()

#End Region

#End Region

#Region " Option Statements "

Option Explicit On
Option Strict On
Option Infer Off

#End Region

#Region " Usage Examples "

'Public Class Form1 : Inherits Form
'
'    Dim ctrlDragger As New ControlDragger
'
'    Private Sub Form1_Load(sender As Object, e As EventArgs) Handles MyBase.Load
'
'        ctrlDragger.AddControl(Me.PictureBox1)
'        Dim ctrlInfo As ControlDragInfo = ctrlDragger.FindControlDragInfo(Me.PictureBox1)
'
'        ctrlInfo.Enabled = True
'        ctrlInfo.Cursor = Cursors.SizeAll

'
'    End Sub
'
'End Class

#End Region

#Region " Imports "

Imports System.Collections.ObjectModel
Imports System.ComponentModel
Imports System.Drawing
Imports System.Windows.Forms
Imports Elektro.Core.Types

#End Region

#Region " Control Dragger "

Namespace UI.Types

    ''' ----------------------------------------------------------------------------------------------------
    ''' <summary>
    ''' Adds dragging capabilities to a single or multiple <see cref="Control"/> when clicking on they client area.
    ''' </summary>
    ''' ----------------------------------------------------------------------------------------------------
    ''' <example> This is a code example.
    ''' <code>
    ''' Public Class Form1 : Inherits Form
    '''
    '''     Dim ctrlDragger As New ControlDragger
    '''
    '''     Private Sub Form1_Load(sender As Object, e As EventArgs) Handles MyBase.Load
    '''
    '''         ctrlDragger.AddControl(Me.PictureBox1)
    '''         Dim ctrlInfo As ControlDragInfo = ctrlDragger.FindControlDragInfo(Me.PictureBox1)
    '''
    '''         ctrlInfo.Enabled = True
    '''         ctrlInfo.Cursor = Cursors.SizeAll
    '''
    '''
    '''     End Sub
    '''
    ''' End Class
    ''' </code>
    ''' </example>
    ''' ----------------------------------------------------------------------------------------------------
    Public NotInheritable Class ControlDragger : Inherits AestheticObject : Implements IDisposable

#Region " Properties "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets an <see cref="IEnumerable(Of Control)"/> collection that contains the
        ''' owner controls that can perform draggable operations.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <value>
        ''' The <see cref="IEnumerable(Of Control)"/>.
        ''' </value>
        ''' ----------------------------------------------------------------------------------------------------
        <EditorBrowsable(EditorBrowsableState.Always)>
        Public ReadOnly Property Controls As ReadOnlyCollection(Of ControlDragInfo)
            <DebuggerStepThrough>
            Get
                Return New ReadOnlyCollection(Of ControlDragInfo)(Me.controlsB.ToArray)
            End Get
        End Property
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' ( Backing field )
        ''' An <see cref="IEnumerable(Of Control)"/> collection that contains the
        ''' owner controls that can perform draggable operations.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Private controlsB As IEnumerable(Of ControlDragInfo)

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Represents a nul <see cref="ControlDragger"/> instance.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <value>
        ''' <see langword="Nothing"/>
        ''' </value>
        ''' ----------------------------------------------------------------------------------------------------
        <EditorBrowsable(EditorBrowsableState.Always)>
        Public Shared ReadOnly Property Empty As ControlDragger
            <DebuggerStepThrough>
            Get
                Return Nothing
            End Get
        End Property

#End Region

#Region " Constructors "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Initializes a new instance of the <see cref="ControlDragger"/> class.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub New()
            Me.controlsB = {}
        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Initializes a new instance of the <see cref="ControlDragger"/> class.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="ctrl">
        ''' The owner <see cref="Control"/> used to perform draggable operations.
        ''' </param>
        '''
        ''' <param name="enabled">
        ''' If set to <see langword="True"/>, inmediately enables dragging on the <see cref="Control"/>.
        ''' </param>
        '''
        ''' <param name="cursor">
        ''' The <see cref="Cursor"/> to use when dragging the <see cref="Control"/>.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub New(ByVal ctrl As Control,
                       Optional enabled As Boolean = False,
                       Optional cursor As Cursor = Nothing)

            Me.controlsB =
                {
                    New ControlDragInfo(ctrl) With
                        {
                            .Enabled = enabled,
                            .Cursor = cursor
                        }
                }

            Me.AddHandlers(ctrl)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Initializes a new instance of the <see cref="ControlDragger"/> class.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="ctrls">
        ''' The owner <see cref="Controls"/> used to perform draggable operations.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub New(ByVal ctrls As IEnumerable(Of Control))

            Me.controlsB = (From ctrl As Control In ctrls Select New ControlDragInfo(ctrl)).ToArray

            For Each c As Control In ctrls
                Me.AddHandlers(c)
            Next c

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Initializes a new instance of the <see cref="ControlDragger"/> class.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="controlInfo">
        ''' The <see cref="FormDragInfo"/> instance that contains the <see cref="Control"/> reference and its draggable info.
        ''' </param>
        '''
        ''' <param name="mouseCoordinates">
        ''' The current mouse coordinates.
        ''' </param>
        '''
        ''' <param name="location">
        ''' The current location.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerNonUserCode>
        Private Sub New(ByVal controlInfo As ControlDragInfo,
                        ByVal mouseCoordinates As Point,
                        ByVal location As Point)

            controlInfo.InitialMouseCoords = mouseCoordinates
            controlInfo.InitialLocation = location

        End Sub

#End Region

#Region " Public Methods "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Assigns the specified <see cref="Control"/> as a draggable element.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="ctrl">
        ''' The <see cref="Control"/>.
        ''' </param>
        '''
        ''' <param name="enabled">
        ''' If set to <see langword="True"/>, inmediatelly enables dragging on the <see cref="Control"/>.
        ''' </param>
        '''
        ''' <param name="cursor">
        ''' The <see cref="Cursor"/> to use when dragging the <see cref="Control"/>.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <exception cref="Global.System.ArgumentException">
        ''' The specified control is already added.;ctrl
        ''' </exception>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub AddControl(ByVal ctrl As Control,
                              Optional enabled As Boolean = False,
                              Optional cursor As Cursor = Nothing)

            For Each controlInfo As ControlDragInfo In Me.controlsB

                If controlInfo.Control.Equals(ctrl) Then
                    Throw New ArgumentException("The specified form is already added.", "form")
                    Exit Sub
                End If

            Next controlInfo

            Dim newControlInfo As New ControlDragInfo(ctrl) With {.Enabled = enabled, .Cursor = cursor}
            Me.controlsB = Me.controlsB.Concat({newControlInfo})
            Me.AddHandlers(ctrl)

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Assigns the specified controls as draggable elements of they parents <see cref="Form"/>.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="ctrls">
        ''' An array of <see cref="Control"/>.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <exception cref="Global.System.ArgumentException">
        ''' The parent form of the control is not handled.
        ''' </exception>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub AddControls(ByVal ctrls As Control())

            For Each ctrl As Control In ctrls
                Me.AddControl(ctrl)
            Next

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Removes the specified <see cref="Control"/> from the draggable elements.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="ctrl">
        ''' The <see cref="Control"/>.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <exception cref="Global.System.ArgumentException">
        ''' The specified control is not found.;ctrl
        ''' </exception>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub RemoveControl(ByVal ctrl As Control)

            Dim controlInfoToRemove As ControlDragInfo = Nothing

            For Each controlInfo As ControlDragInfo In Me.controlsB

                If controlInfo.Control.Equals(ctrl) Then
                    controlInfoToRemove = controlInfo
                    Exit For
                End If

            Next controlInfo

            If (controlInfoToRemove IsNot Nothing) Then

                Me.controlsB = (From controlInfo As ControlDragInfo In Me.controlsB
                                Where Not controlInfo.Equals(controlInfoToRemove))

                controlInfoToRemove.Enabled = False
                Me.RemoveHandlers(controlInfoToRemove.Control)

            Else
                Throw New ArgumentException("The specified control is not found.", "ctrl")

            End If

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Removes the specified controls from the draggable elements.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="ctrls">
        ''' An array of <see cref="Control"/>.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub RemoveControls(ByVal ctrls As Control())

            For Each ctrl As Control In ctrls
                Me.RemoveControl(ctrl)
            Next

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Finds the <see cref="ControlDragInfo"/> instance that is associated with the specified <see cref="Control"/>.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="ctrl">
        ''' The <see cref="Control"/>.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The <see cref="ControlDragInfo"/> instance that is associated with the specified <see cref="Control"/>.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Function FindControlDragInfo(ByVal ctrl As Control) As ControlDragInfo

            Return (From controlInfo As ControlDragInfo In Me.controlsB
                    Where controlInfo.Control.Equals(ctrl)
                    ).SingleOrDefault

        End Function

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Finds the <see cref="ControlDragInfo"/> instance that is associated with the specified <see cref="Control"/>.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="controlName">
        ''' The name of the <see cref="Control"/>.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The <see cref="FormDragInfo"/> instance that is associated with the specified <see cref="Control"/> .
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Function FindControlDragInfo(ByVal controlName As String,
                                            Optional stringComparison As StringComparison =
                                                     StringComparison.OrdinalIgnoreCase) As ControlDragInfo

            Return (From controlInfo As ControlDragInfo In Me.controlsB
                    Where controlInfo.Name.Equals(controlName, stringComparison)
                    ).SingleOrDefault

        End Function

#End Region

#Region " Private Methods "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Adds the <see cref="Control"/> handlers to enable draggable operations.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="ctrl">
        ''' The <see cref="Control"/>.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Private Sub AddHandlers(ByVal ctrl As Control)

            AddHandler ctrl.MouseDown, AddressOf Me.Element_MouseDown
            AddHandler ctrl.MouseUp, AddressOf Me.Element_MouseUp
            AddHandler ctrl.MouseMove, AddressOf Me.Element_MouseMove
            ' AddHandler ctrl.MouseEnter, AddressOf Me.Element_MouseEnter
            ' AddHandler ctrl.MouseLeave, AddressOf Me.Element_MouseLeave

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Removes the <see cref="Control"/> handlers to disable draggable operations.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="ctrl">
        ''' The <see cref="Control"/>.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Private Sub RemoveHandlers(ByVal ctrl As Control)

            If Not (ctrl.IsDisposed) AndAlso Not (ctrl.Disposing) Then

                RemoveHandler ctrl.MouseDown, AddressOf Me.Element_MouseDown
                RemoveHandler ctrl.MouseUp, AddressOf Me.Element_MouseUp
                RemoveHandler ctrl.MouseMove, AddressOf Me.Element_MouseMove
                ' RemoveHandler ctrl.MouseEnter, AddressOf Me.Element_MouseEnter
                ' RemoveHandler ctrl.MouseLeave, AddressOf Me.Element_MouseLeave

            End If

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Return the new control location.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="controlInfo">
        ''' The <see cref="ControlDragInfo"/> instance that contains the <see cref="Control"/> instance and its info.
        ''' </param>
        '''
        ''' <param name="currentLocation">
        ''' The current form location.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The new control location.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Private Function GetNewLocation(ByVal controlInfo As ControlDragInfo,
                                        ByVal currentLocation As Point) As Point

            Dim x As Integer = (controlInfo.InitialLocation.X + (currentLocation.X - controlInfo.InitialMouseCoords.X))
            Dim y As Integer = (controlInfo.InitialLocation.Y + (currentLocation.Y - controlInfo.InitialMouseCoords.Y))
            Return New Point(x, y)

        End Function

#End Region

#Region " Event Handlers "

        ' ''' ----------------------------------------------------------------------------------------------------
        ' ''' <summary>
        ' ''' Handles the <see cref="Control.Disposed"/> event of the owner controls.
        ' ''' </summary>
        ' ''' ----------------------------------------------------------------------------------------------------
        ' ''' <param name="sender">
        ' ''' The source of the event.
        ' ''' </param>
        ' '''
        ' ''' <param name="e">
        ' ''' The <see cref="MouseEventArgs"/> instance containing the event data.
        ' ''' </param>
        ' ''' ----------------------------------------------------------------------------------------------------
        'Private Sub Element_Disposed(ByVal sender As Object, ByVal e As MouseEventArgs)
        '
        'End Sub

        ' ''' ----------------------------------------------------------------------------------------------------
        ' ''' <summary>
        ' ''' Handles the <see cref="Control.MouseEnter"/> event of the owner controls.
        ' ''' </summary>
        ' ''' ----------------------------------------------------------------------------------------------------
        ' ''' <param name="sender">
        ' ''' The source of the event.
        ' ''' </param>
        ' '''
        ' ''' <param name="e">
        ' ''' The <see cref="EventArgs"/> instance containing the event data.
        ' ''' </param>
        ' ''' ----------------------------------------------------------------------------------------------------
        'Private Sub Element_MouseEnter(ByVal sender As Object, ByVal e As EventArgs)
        '
        '    Dim controlInfo As ControlDragInfo = Me.FindFormDragInfo(DirectCast(sender, Control))
        '
        '    controlInfo.CursorNormal = controlInfo.Control.Cursor
        '
        '    If (controlInfo.Enabled) Then
        '        controlInfo.Control.Cursor = controlInfo.Cursor
        '        ' Optionally:
        '        ' controlInfo.Form.BringToFront()
        '    End If
        '
        'End Sub

        ' ''' ----------------------------------------------------------------------------------------------------
        ' ''' <summary>
        ' ''' Handles the <see cref="Control.MouseLeave"/> event of the owner controls.
        ' ''' </summary>
        ' ''' ----------------------------------------------------------------------------------------------------
        ' ''' <param name="sender">
        ' ''' The source of the event.
        ' ''' </param>
        ' '''
        ' ''' <param name="e">
        ' ''' The <see cref="EventArgs"/> instance containing the event data.
        ' ''' </param>
        ' ''' ----------------------------------------------------------------------------------------------------
        'Private Sub Element_MouseLeave(ByVal sender As Object, ByVal e As EventArgs)
        '
        '    Dim controlInfo As ControlDragInfo = Me.FindFormDragInfo(DirectCast(sender, Control))
        '
        '    controlInfo.Control.Cursor = controlInfo.CursorNormal
        '
        'End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Handles the <see cref="Control.MouseDown"/> event of the owner controls.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="sender">
        ''' The source of the event.
        ''' </param>
        '''
        ''' <param name="e">
        ''' The <see cref="MouseEventArgs"/> instance containing the event data.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        Private Sub Element_MouseDown(ByVal sender As Object, ByVal e As MouseEventArgs)

            Dim controlInfo As ControlDragInfo = Me.FindControlDragInfo(DirectCast(sender, Control))

            If (controlInfo.Enabled) Then
                controlInfo.Control.BringToFront()
                controlInfo.Control.Cursor = controlInfo.Cursor
                controlInfo.DragInfo = New ControlDragger(controlInfo, Control.MousePosition, controlInfo.Control.Location)
            End If

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Handles the <see cref="Control.MouseUp"/> event of the owner controls.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="sender">
        ''' The source of the event.
        ''' </param>
        '''
        ''' <param name="e">
        ''' The <see cref="MouseEventArgs"/> instance containing the event data.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        Private Sub Element_MouseUp(ByVal sender As Object, ByVal e As MouseEventArgs)

            Dim controlInfo As ControlDragInfo = Me.FindControlDragInfo(DirectCast(sender, Control))

            controlInfo.DragInfo = ControlDragger.Empty
            controlInfo.Control.Cursor = controlInfo.CursorNormal

        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Handles the <see cref="Control.MouseMove"/> event of the owner controls.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="sender">
        ''' The source of the event.
        ''' </param>
        '''
        ''' <param name="e">
        ''' The <see cref="MouseEventArgs"/> instance containing the event data.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        Private Sub Element_MouseMove(ByVal sender As Object, ByVal e As MouseEventArgs)

            Dim controlInfo As ControlDragInfo = Me.FindControlDragInfo(DirectCast(sender, Control))

            If (controlInfo.Enabled) AndAlso (controlInfo.DragInfo IsNot ControlDragger.Empty) Then
                controlInfo.Control.Location = controlInfo.DragInfo.GetNewLocation(controlInfo, Control.MousePosition)
            End If

        End Sub

#End Region

#Region " IDisposable Implementation "

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Flag to detect redundant calls when disposing.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Private isDisposed As Boolean = False

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Releases all the resources used by this instance.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Public Sub Dispose() Implements IDisposable.Dispose
            Me.Dispose(isDisposing:=True)
            GC.SuppressFinalize(obj:=Me)
        End Sub

        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
        ''' Releases unmanaged and, optionally, managed resources.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="isDisposing">
        ''' <see langword="True"/>  to release both managed and unmanaged resources;
        ''' <see langword="False"/> to release only unmanaged resources.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        Protected Sub Dispose(ByVal isDisposing As Boolean)

            If (Not Me.isDisposed) AndAlso (isDisposing) Then

                For Each formInfo As ControlDragInfo In Me.controlsB

                    With formInfo

                        .Enabled = False
                        .CursorNormal = Nothing
                        .DragInfo = ControlDragger.Empty
                        .InitialMouseCoords = Point.Empty
                        .InitialLocation = Point.Empty

                        Me.RemoveHandlers(.Control)

                    End With ' form

                Next formInfo

                Me.controlsB = Nothing

            End If

            Me.isDisposed = True

        End Sub

#End Region

    End Class

End Namespace

#End Region