HitTest Method

Description

Returns hit test information for a given X and Y pixel on the screen.

Syntax

Public Function HitTest( _
    ByVal x As Long, _
    ByVal y As Long _
) As GridHitTestInfo

Parameters

x: X coordinate
y: Y coordinate

Return Type

Returns a GridHitTestInfo about the given X and Y coordinates.

Remarks

Use this method to determine if the GridControl is at a given X and Y coordinate and which part of the GridControl is positioned at the given pixel (Row, item, column, group box, etc.).

This method can also be used to return a reference to rows, items, and columns that are at a given X and Y coordinate.

The HitTest method is particularly useful in mouse events to return the exact row, column, and item that was clicked. The name can be misleading; you do not need to use the HitTest method in a mouse event.

Example

HitTest Sample (Visual Basic)

This sample illustrates how you could use the HitTest method in a MouseDown event.

Private Sub wndGridControl_MouseDown(Button As Integer, Shift As Integer, X As Long, Y As Long)  

    Dim hitColumn As GridColumn  
    Dim hitRow As GridRow  
    Dim hitItem As GridRecordItem  

    ' The MouseDown event is being used to illustrate how the HitTest method can be used. The HitTest method does not have  
    ' to be used with a mouse event; it can be used to test any X and Y coordinate on the screen to see if the GridControl  
    ' occupies these pixels and what part of the GridControl is at the specified pixel (Group Box, Row, Item, etc).  
    ' If it is determined that a GridControl component is at the X and Y coordinates, the HitTest method can return a  
    ' reference to that component (Column, Row, Record, Item, etc...).  

    ' Determines which part of the GridControl the mouse was positioned over when clicked.  
    Select Case wndGridControl.HitTest(X, Y).ht  
        ' If MouseDown while positioned anywhere over the Group Box (Even over Column Headers in Group Box)  
        Case xtpHitTestGroupBox:  
            Debug.Print "MouseDown in Group Box"  
        ' If MouseDown while positioned anywhere over the ColumnHeader area. This does NOT include  
        ' column header in the Group Box  
        Case xtpHitTestHeader:  
            Debug.Print "MouseDown in Column Header Area (Not in Group Box)"  
        ' If MouseDown while positioned over the Grid Area, this would include rows, columns, items, group rows, expand buttons  
        Case xtpHitTestGridArea:  
            Debug.Print "MouseDown in Grid Area"  
        ' This case will never happen, Unknown is returned when HitTest is called and the mouse is positioned  
        ' over an area outside of the Grid control  
        Case xtpHitTestUnknown:  
            Debug.Print "Mouse is in an Unknown Area"  
    End Select  

    ' Returns a reference to the column clicked  
    ' Determines which column the mouse is positioned over on MouseDown; this will also be executed  
    ' if the column header in the Group By box is clicked. This will be true if any item in the column  
    ' is clicked, not just column headers.  
    Set hitColumn = wndGridControl.HitTest(X, Y).Column  
    If Not hitColumn Is Nothing Then  
        Debug.Print "MouseDown on Column header: " & hitColumn.Caption  
    End If  

    ' Returns a reference to the row clicked  
    ' Determines which row the mouse was positioned over on MouseDown.  
    Set hitRow = wndGridControl.HitTest(X, Y).Row  
    If Not hitRow Is Nothing Then  
        If hitRow.GroupRow Then  
            Debug.Print "MouseDown on GroupRow"  
        Else  
            Debug.Print "MouseDown on Row # " & hitRow.Index  
        End If  
    End If  

    ' Returns a reference to the item clicked  
    ' Determines which row the mouse was positioned over on MouseDown.  
    Set hitItem = wndGridControl.HitTest(X, Y).Item  
    If Not hitItem Is Nothing Then  
        If Not wndGridControl.PreviewMode Then  
            Debug.Print "MouseDown on Item: " & hitItem.Value & " in column: " & hitColumn.Caption  
        ElseIf Not (hitRow.Record.PreviewText = "") Then  
            Debug.Print "MouseDown on PreviewText"  
        End If  
    End If  
End Sub