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;
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 [out, optional]
-
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 [out]
-
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 | Windows Store apps] |
|---|---|
|
Minimum supported server |
Windows Server 2008 R2, Windows Server 2008 with SP2 and Platform Update for Windows Server 2008 [desktop apps | Windows Store apps] |
|
Minimum supported phone |
Windows Phone 8.1 [Windows Phone Silverlight 8.1 and Windows Runtime apps] |
|
Header |
|
|
Library |
|
|
DLL |
|
See also