Edit

Share via

ITfContextOwner::GetACPFromPoint method (msctf.h)

  • Article

The ITfContextOwner::GetACPFromPoint method converts a point in screen coordinates to an application character position.

Syntax

HRESULT GetACPFromPoint(
  [in]  const POINT *ptScreen,
  [in]  DWORD       dwFlags,
  [out] LONG        *pacp
);

Parameters

[in] ptScreen

Pointer to the POINT structure with the screen coordinates of the point.

[in] dwFlags

Specifies the character position to return based upon the screen coordinates of the point relative to a character bounding box. By default, the character position returned is the character bounding box containing the screen coordinates of the point. If the point is outside a character's bounding box, the method returns NULL or TF_E_INVALIDPOINT.

If the GXFPF_ROUND_NEAREST flag is specified for this parameter and the screen coordinates of the point are contained in a character bounding box, the character position returned is the bounding edge closest to the screen coordinates of the point.

If the GXFPF_NEAREST flag is specified for this parameter and the screen coordinates of the point are not contained in a character bounding box, the closest character position is returned.

The bit flags can be combined.

[out] pacp

Receives the character position that corresponds to the screen coordinates of the point

Return value

This method can return one of these values.

Value Description
S_OK
 The method was successful.
TS_E_INVALIDPOINT
 The ptScreen parameter is not within the bounding box of any character.
TS_E_NOLAYOUT
 The application has not calculated a text layout.

Remarks

Point 1 is in character bounding box and point 2 is outside the character bounding box. Use the illustration to determine the character position returned based on the flags used in the dwFlags parameter.

Point 1

  • Default-- pacp = 0 --The screen coordinates of the point is inside the character bounding box of Character Position 0.
  • GXFPF_ROUND_NEAREST-- pacp = 1 --The screen coordinates of the point is closest to Range Position 1 which is the starting range position of Character Position 1.
  • GXFPF_NEAREST-- pacp = 0 --The default behavior occurs because the point lies within the character bounding box of Character Position 0.
Point 2
  • Default-- hr = TF_E_INVALIDPOINT --The screen coordinates of the point is outside a character bounding box.
  • GXFPF_ROUND_NEAREST-- hr = TF_E_INVALIDPOINT --The default behavior occurs because the screen coordinates of the point is outside a character bounding box.
  • GXFPF_NEAREST-- pacp = 1 --The closest character position to the screen coordinates of the point is Character Position 1.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header msctf.h
DLL Msimtf.dll
Redistributable TSF 1.0 on Windows 2000 Professional

See also

ITextStoreACP::GetACPFromPoint

ITfContextOwner

ITfContextView::GetRangeFromPoint

TsViewCookie