IDWriteTextLayout::HitTestTextRange method

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 <a href="https://msdn.microsoft.com/0d687337-8623-4014-967c-f533072e31cc">IDWriteTextLayout</a>::GetLineLengths),
 and the maxBidiReorderingDepth value from the <a href="https://msdn.microsoft.com/4524ace3-fca6-4daf-9ecb-516771e53fc9">DWRITE_TEXT_METRICS</a>structure of the output argument *textMetrics (from the function
 <a href="https://msdn.microsoft.com/73a85977-5c24-4abc-ad8c-1d0d6474bd7e">IDWriteFactory</a>::<a href="https://msdn.microsoft.com/f76f85df-112f-4bc3-b922-a0d7940d2954">CreateTextLayout</a>).

Syntax

HRESULT HitTestTextRange(
  UINT32                  textPosition,
  UINT32                  textLength,
  FLOAT                   originX,
  FLOAT                   originY,
  DWRITE_HIT_TEST_METRICS *hitTestMetrics,
  UINT32                  maxHitTestMetricsCount,
  UINT32                  *actualHitTestMetricsCount
);

Parameters

textPosition

Type: UINT32

The first text position of the specified range.

textLength

Type: UINT32

The number of positions of the specified range.

originX

Type: FLOAT

The origin pixel location X at the left of the layout box. This offset is added to the hit-test metrics returned.

originY

Type: FLOAT

The origin pixel location Y at the top of the layout box. This offset is added to the hit-test metrics returned.

hitTestMetrics

Type: DWRITE_HIT_TEST_METRICS*

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.

maxHitTestMetricsCount

Type: UINT32

Maximum number of boxes hitTestMetrics could hold in its buffer memory.

actualHitTestMetricsCount

Type: UINT32*

Actual number of geometries hitTestMetrics holds in its buffer memory.

Return Value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Requirements

   
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]
Target Platform Windows
Header dwrite.h
Library Dwrite.lib
DLL Dwrite.dll

See Also

IDWriteTextLayout