Функция GetPointerFrameTouchInfo (winuser.h)
Возвращает весь кадр сенсорной информации для указанных указателей (типа PT_TOUCH), связанных с текущим сообщением.
Синтаксис
BOOL GetPointerFrameTouchInfo(
[in] UINT32 pointerId,
[in, out] UINT32 *pointerCount,
[out] POINTER_TOUCH_INFO *touchInfo
);
Параметры
[in] pointerId
Идентификатор указателя, для которого требуется получить сведения о кадре.
[in, out] pointerCount
Указатель на переменную, указывающую количество структур в буфере, на которые указывает touchInfo. Если getPointerFrameTouchInfo завершается успешно, параметр pointerCount обновляется с учетом общего количества указателей в кадре.
[out] touchInfo
Адрес массива POINTER_TOUCH_INFO структур для получения сведений указателя. Этот параметр может иметь значение NULL, если *pointerCount равно нулю.
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение не равно нулю.
Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Комментарии
Устройства с параллельным режимом могут сообщать о входных данных указателя в кадрах, то есть они могут сообщать о состоянии и положении всех указателей с этого устройства в одном входном отчете в систему. В идеале приложения должны рассматривать весь кадр как единый вход, если только требования конкретного приложения не диктуют иное.
GetPointerFrameTouchInfo извлекает весь входной кадр указателя, связанный с сообщением указателя (типа PT_TOUCH). Используйте GetPointerTouchInfo для получения сведений об одном указателе, связанном с сообщением указателя.
Фрейм содержит только указатели, которые в настоящее время принадлежат тому же окну, что и указанный указатель.
Сведения, возвращаемые GetPointerFrameTouchInfo , связаны с последним сообщением указателя, извлеченным вызывающим потоком. Когда вызывающий поток извлекает следующее сообщение, сведения, связанные с предыдущим сообщением, могут быть недоступны.
Если приложение не обрабатывает входные сообщения указателя так быстро, как они создаются, некоторые сообщения могут быть объединены в сообщение WM_POINTERUPDATE . Используйте GetPointerFrameTouchInfoHistory , чтобы получить журнал сообщений из последнего сообщения WM_POINTERUPDATE .
Получив весь кадр сведений, приложение может затем вызвать функцию SkipPointerFrameMessages , чтобы пропустить оставшиеся сообщения указателя, связанные с этим кадром, ожидающие извлечения. Это позволяет приложению сэкономить затраты на получение и обработку оставшихся сообщений по одному. Однако функцию SkipPointerFrameMessages следует использовать с осторожностью и только в том случае, если вызывающий объект может быть уверен, что ни одна другая сущность в потоке вызывающего объекта не ожидает видеть остальные сообщения указателя по одному по мере их извлечения.
Обратите внимание, что полученные сведения связаны с кадром указателя, который последний раз был получен вызывающим потоком. Когда вызывающий поток получает следующее сообщение, сведения, связанные с предыдущим кадром указателя, могут перестать быть доступными.
Если рамка указателя не содержит дополнительных указателей, кроме указанного указателя, эта функция выполняется успешно и возвращает только сведения для указанного указателя.
Если сведения, связанные с рамкой указателя, больше недоступны, эта функция завершается ошибкой с последней ошибкой ERROR_NO_DATA.
Если вызывающий поток не владеет окном, в которое было доставлено сообщение указателя, эта функция завершается ошибкой с последней ошибкой ERROR_ACCESS_DENIED.
Если указанный указатель не имеет типа PT_TOUCH, эта функция завершается ошибкой с последней ошибкой ERROR_DATATYPE_MISMATCH.
Для приложений, имеющих как клиентские, так и не клиентские области, входной кадр может включать как клиентские, так и не клиентские данные. Чтобы различать данные клиента и данные, не относящиеся к клиенту, необходимо выполнить проверку попадания в целевом окне.
Если требуется отфильтровать данные из входного кадра, рекомендуется следующее:
- Для каждого обновления, не включающего контакт указателя ( POINTER_FLAG_UPDATE без POINTER_FLAG_INCONTACT), нажмите тест, чтобы определить, является ли входные данные клиентскими или не клиентскими.
- Для каждого нового контакта (POINTER_FLAG_DOWN) нажмите тест, чтобы определить, являются ли входные данные клиентскими или не клиентскими, и отслеживать эти сведения.
- Для каждого обновления, включающего контакт указателя ( POINTER_FLAG_UPDATE с POINTER_FLAG_INCONTACT), используйте сведения для отслеживания, чтобы определить, являются ли входные данные клиентскими или не клиентскими.
- Для каждого POINTER_FLAG_UP используйте сведения для отслеживания, чтобы определить, являются ли входные данные клиентскими или не клиентскими, а затем очистите этот указатель из данных отслеживания.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 8 [только классические приложения] |
| Минимальная версия сервера | Windows Server 2012 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winuser.h (включая Windows.h) |
| Библиотека | User32.lib |
| DLL | User32.dll |
| Набор API | ext-ms-win-rtcore-ntuser-wmpointer-l1-1-0 (появилось в Windows 10, версия 10.0.14393) |