The application calls this function to get a set of hit-test metrics corresponding to a range of text positions. One of the main usages is to implement highlight selection of the text string.
The function returns E_NOT_SUFFICIENT_BUFFER, which is equivalent to HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER), when the buffer size of hitTestMetrics is too small to hold all the regions calculated by the function. In this situation, the function sets the output value *actualHitTestMetricsCount to the number of geometries calculated.
The application is responsible for allocating a new buffer of greater size and calling the function again.
A good value to use as an initial value for maxHitTestMetricsCount may be calculated from the following equation:
maxHitTestMetricsCount = lineCount * maxBidiReorderingDepth
where lineCount is obtained from the value of the output argument *actualLineCount (from the function IDWriteTextLayout::GetLineLengths), and the maxBidiReorderingDepth value from the DWRITE_TEXT_METRICSstructure of the output argument *textMetrics (from the function IDWriteFactory::CreateTextLayout).
HRESULT HitTestTextRange( UINT32 textPosition, UINT32 textLength, FLOAT originX, FLOAT originY, DWRITE_HIT_TEST_METRICS *hitTestMetrics, UINT32 maxHitTestMetricsCount, UINT32 *actualHitTestMetricsCount );
The first text position of the specified range.
The number of positions of the specified range.
The origin pixel location X at the left of the layout box. This offset is added to the hit-test metrics returned.
The origin pixel location Y at the top of the layout box. This offset is added to the hit-test metrics returned.
When this method returns, contains a pointer to a buffer of the output geometry fully enclosing the specified position range. The buffer must be at least as large as maxHitTestMetricsCount.
Maximum number of boxes hitTestMetrics could hold in its buffer memory.
Actual number of geometries hitTestMetrics holds in its buffer memory.
If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
|Minimum supported client||Windows 7, Windows Vista with SP2 and Platform Update for Windows Vista [desktop apps | UWP apps]|
|Minimum supported server||Windows Server 2008 R2, Windows Server 2008 with SP2 and Platform Update for Windows Server 2008 [desktop apps | UWP apps]|