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 IDWriteTextLayout::GetLineLengths), and the maxBidiReorderingDepth value from the DWRITE_TEXT_METRICS structure of the output argument *textMetrics (from the function IDWriteFactory::CreateTextLayout).

Syntax

virtual HRESULT HitTestTextRange(
  UINT32  textPosition,
  UINT32  textLength,
  FLOAT  originX,
  FLOAT  originY,
  [out, optional]  DWRITE_HIT_TEST_METRICS * hitTestMetrics,
  UINT32  maxHitTestMetricsCount,
  [out]            UINT32 * actualHitTestMetricsCount
) = 0;

Parameter

• textPosition
  The first text position of the specified range.

• textLength
  The number of positions of the specified range.

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

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

• hitTestMetrics [out, optional]
  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
  Maximum number of boxes hitTestMetrics could hold in its buffer memory.

• actualHitTestMetricsCount [out]
  Actual number of geometries hitTestMetrics holds in its buffer memory.

Rückgabewert

Ist Methode erfolgreich, wird "S_OK" zurückgegeben. Andernfalls wird ein HRESULT-Fehlercode zurückgegeben.

Anforderungen

Siehe auch

IDWriteTextLayout