DOCUMENT:Q185882 11-AUG-1998 [vbwin] TITLE :HOWTO: Use the HitTest Event and HitBehavior Property PRODUCT :Microsoft Visual Basic for Windows PROD/VER: OPER/SYS:WINDOWS KEYWORDS: ====================================================================== --------------------------------------------------------------------- The information in this article applies to: - Microsoft Visual Basic Learning, Professional, and Enterprise Editions for Windows, version 6.0 --------------------------------------------------------------------- SUMMARY ======= This article discusses a new Event-Property pair available for UserControls created using Visual Basic 6.0. The general purpose of the HitTest Event, and the HitBehavior Property is to give greater flexibility in responding to UserControl events. Specifically, this article demonstrates how to build a transparent UserControl that responds to mouse events. This was not possible in previous versions of Visual Basic. MORE INFORMATION ================ Using HitTest is relatively straightforward. "HitResult" is a value that is passed into the HitTest event by the system. By examining the value of HitResult, you can determine on which area of the control the mouse event occurred. Based on that information, you can reset the value of HitResult to have the control respond in the desired manner. You can instruct the control to process the mouse event, or you can instruct the control to pass the event on to the container. The default settings for the HitBehavior Property do not need to be changed for these examples. For the examples used here, there are two different scenarios depending on whether or not the UserControl has been masked using MaskPicture and MaskColor. If your UserControl does not have a masked area please see the section entitled "Capturing Mouse Events on a Transparent UserControl." If your UserControl has a masked area, please see the section entitled "Capturing Mouse Events on a Masked Usercontrol." It is important to note that the HitTest event occurs only on a Windowless UserControl with the BackStyle property set to Transparent. Windowless UserControls are also new to Visual Basic 6.0. Capturing Mouse Events on a Transparent UserControl --------------------------------------------------- 1. Create a New Standard EXE project. 2. Add a UserControl to the project. (You may receive a warning that the UserControl can not be Public in this type of project. Choose OK in response to this message.) 3. Set the BackStyle property of the UserControl to Transparent. 4. Set the Windowless property of the UserControl to True. 5. Add the following code to the UserControl's module: Private Sub UserControl_Click() Debug.Print "Usercontrol Click" End Sub Private Sub UserControl_DblClick() Debug.Print "Usercontrol Doubleclick" End Sub Private Sub UserControl_HitTest(X As Single, Y As Single, _ HitResult As Integer) 'Instruct the UserControl to behave as if the click occurred on a ' painted region of the control. If HitResult = vbHitResultOutside Then HitResult = vbHitResultHit End If End Sub 6. Place the UserControl on Form1. You may wish to draw a rectangle or other shape around the control since the control will not be visible. 7. Run the project. 8. Clicking or double-clicking the UserControl should result in the display of the message boxes. Capturing Mouse Events on a Masked UserControl ---------------------------------------------- This example requires a UserControl set up to use the MaskPicture and MaskColor Properties. For more information on using the MaskPicture and MaskColor properties, please see the article listed in the REFERENCES section. 1. Create a bitmap with a white background that contains a filled red circle. 2. Perform steps 1-4 from the previous section. 3. Set the following properties for the UserControl: BackStyle: 0 - Transparent MaskColor: &H00FFFFFF& 'White MaskPicture: The bitmap created in Step 1. BackColor: &H000000FF& 'Red 4. Add the following code to the UserControl: Private Sub UserControl_Click() Debug.Print "Usercontrol Click" End Sub 5. Add the following code to Form1: Private Sub Form_Click() Debug.Print "Form Click" End Sub 6. Run the project. Click the masked (or visible) portion of the UserControl. You should see the "UserControl Click" message box. Clicking the transparent area of the control should cause the "Form Click" message box to display. This is the default behavior of a masked control - events on the painted area will be processed by the control and events on the transparent area will be forwarded to the container. 7. The event process behavior can be modified at this point to create separate responses based on which area of the UserControl received the Mouse event. 8. Add the following code to the General Section of the UserControl's module: Private HitTestFlag As Integer Private Sub UserControl_HitTest(X As Single, Y As Single, _ HitResult As Integer) HitTestFlag = HitResult 'Set the UserControl to respond to the event. HitResult = vbHitResultHit End Sub 9. Replace the UserControl_Click event created in step 2 with the following: Private Sub UserControl_Click() If HitTestFlag = vbHitResultOutside Then Debug.Print "usercontrol transparent area click" ElseIf HitTestFlag = vbHitResultHit Then Debug.Print "usercontrol painted area click" End If End Sub 10. Run the project. Clicking the Masked area of the control should display the "painted area click" message. Clicking the transparent area of the control should display the "transparent area click" message. Using X and Y Coordinates with HitTest -------------------------------------- Along with the HitResult argument, the X and Y coordinates of the mouse event are also passed into the HitText Event. The ability to determine whether the event occurred on a transparent area of the control or a masked area of the control can be sufficient in many cases. However, it may be necessary to determine if the event occurred on a specific area on the control. The X and Y coordinates can be used to accomplish this. The following example demonstrates a simple scenario. For the example, we will determine over which quadrant of a UserControl the mouse pointer is currently positioned. 1. Start a new Standard EXE project in Visual Basic 6.0. 2. Add a Usercontrol to the project. 3. Set the Windowless property of the UserControl to True. 4. Set the BackStyle property of the UserControl to Transparent. 5. Add the following code to the UserControl module: Private Sub UserControl_HitTest(X As Single, Y As Single, _ HitResult As Integer) Dim txtDisplay As String With UserControl If Y < .Height / 2 Then txtDisplay = "Upper " Else txtDisplay = "Lower " End If If X < .Width / 2 Then txtDisplay = txtDisplay & "Left" Else txtDisplay = txtDisplay & "Right" End If End With Parent.Label1.Caption = txtDisplay End Sub 6. Add a Label to the Form. 7. Add the UserControl to Form1. You may wish to draw a square or rectangle around the control since it will not be visible. You may also want to display a picture on the form using the form's Picture property. 8. Set the BackStyle of the Label to Transparent. 9. Run the Project. As you move the mouse over the UserControl, the text in the Label control changes as you move from one quadrant to another. The HitBehavior Property ------------------------ The HitBehavior is settable at design time or run-time, and controls how HitTest works. There are three options, which are explained in Online Help. Since HitBehavior has the potential to effect logical evaluations in your code, it is important to understand the differences and determine which HitBehavior is desirable before you write the code. Summary ------- HitTest and HitBehavior are new features in Visual Basic 6.0. These features allow event handling on transparent UserControls that was not possible in previous versions. There are many possible combinations when using HitTest, HitBehavior, and XY coordinates. They could be used to create any number of behaviors, ToolTips or HotSpots for example. Keep in mind that these properties and events are available for Windowless, Transparent UserControls only. REFERENCES ========== For additional information on using the MaskPicture and MaskColor properties, please see the following article(s) in the Microsoft Knowledge Base: ARTICLE-ID: Q174216 TITLE : TransparentPaint Backstyle Option Unavailable Additional query words: kbDSupport kbDSD kbCtrlCreate kbVBp600 kbVBp ====================================================================== Platform : WINDOWS Issue type : kbhowto ============================================================================= THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY. Copyright Microsoft Corporation 1998.