IXRHitTestResults (Compact 2013)

Article
04/19/2017

3/28/2014

This C++ class contains information about the UI objects that are affected during a hit test.

This class supports the methods on the IUnknown interface.

Syntax

class IXRHitTestResults : public IUnknown

Inheritance Hierarchy

IUnknown

IXRHitTestResults

Methods

Method	Description
IXRHitTestResults::GetCount	Retrieves the number of items in this hit-test results object.
IXRHitTestResults::GetItem	Retrieves the item at the specified index in this hit-test results object.

Thread Safety

Members of this class are thread safe if you previously called IXRApplication::CreateHostFromXaml and supplied it with an XRWindowCreateParams structure that has AllowsMultipleThreadAccess set to true.

Remarks

IXRHitTestResults provides information about the results of a hit test. Hit testing is the process by which XAML for Windows Embedded takes input stimulus (such as mouse clicks) from the application, and then determines which IXRUIElement object in the layout and visual tree to designate as the source of the input event.

Do not create a new IXRHitTestResults object. To retrieve this object, call IXRUIElement::HitTest.

Note

UI objects that can be used for hit testing must return true when the IXRUIElement::GetIsHitTestVisible method is called. If this method returns false, the element will not report any input events, such as MouseLeftButtonDown.

Use an IXRHitTestResultsPtr smart pointer instead of a raw interface pointer. For more information, see XRPtr<Interface>.

If the value that IXRHitTestResults::GetCount retrieves is greater than 0 (zero), you can iterate through the objects by calling IXRHitTestResults::GetItem for each iteration, to retrieve a pointer to each affected object. These are all objects hit by the hit tests, in direct relationship with the zIndex property value. The objects are not affected by the hit test itself; this only provides information to the caller as to what is located at these coordinates of the scene.

For more information about hit-testing concepts, see Hit Testing and Input Events on MSDN.

Example

The following example code conducts a hit test for an IXRUIElement object and captures the results in an IXRHitTestResults object.

To run the code example, both an object derived from IXRUIElement and an XRRect structure must be created, and the object derived from IXRUIElement must be visible for hit testing and in the visual tree.

Important

For readability, the following code example does not contain security checking or error handling. Do not use the following code in a production environment.

#include "windows.h"
#include "XamlRuntime.h"
#include "XRPtr.h"


void GetAffectedObjects(IXRUIElement* pUIElement, XRRect* rect)
{
  // Perform a hit test and retrieve hit-test results

  IXRHitTestResults* pResults;
  pUIElement->HitTest(rect, &pResults);

   // Get the count of elements affected by the hit test

  int count = 0;
  pResults->GetCount(&count);

  // Retrieve the name of each affected object

  IXRUIElementPtr pAffectedObject;
  WCHAR* szObjName;

  for (int i = 0;i<count; i++)
  {
    pResults->GetItem(i, &pAffectedObject);
    pAffectedObject->GetName(&szObjName); 
    DEBUGMSG(TRUE, (TEXT("An object affected by this hit test is %u\r\n"), szObjName)); 
    
  }
}

.NET Framework Equivalent

None.

Requirements

Header	XamlRuntime.h
sysgen	SYSGEN_XAML_RUNTIME

Share via