IXRHitTestResults (Compact 2013)
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
IXRHitTestResults
Methods
Method |
Description |
|---|---|
Retrieves the number of items in this hit-test results object. |
|
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 |