Сведения о элементах управления подсказками

Подсказки отображаются автоматически или всплывают, когда пользователь приостанавливает указатель мыши на инструмент или другой элемент пользовательского интерфейса. Подсказка отображается рядом с указателем и исчезает, когда пользователь нажимает кнопку мыши, перемещает указатель от инструмента или просто ожидает несколько секунд.

Элемент управления подсказки на следующем рисунке отображает сведения о файле на рабочем столе Windows. При перемещении мыши на иллюстрацию вы также увидите динамическую подсказку, содержащую описательный текст.

В этом разделе описывается, как работают элементы управления подсказками и как их создать.

• Поведение и внешний вид подсказки
• Создание элементов управления всплывающими подсказками
• активация элементов управления подсказками
• вспомогательные средства
• отображение текста
• Сообщения и Уведомления
• Проверка на пересечение
• обработка сообщений по умолчанию

Поведение и внешний вид подсказки

Элементы управления подсказками могут отображать одну строку текста или несколько строк. Их углы могут быть округленными или квадратными. Они могут или не иметь стебля, который указывает на инструменты, как мультипликационный речевой шар. Текст подсказки может быть стационарным или может перемещаться с указателем мыши, который называется отслеживанием. Стационарный текст может отображаться рядом с инструментом или над ним, что называется "на месте". Стандартные подсказки являются стационарными, отображают одну строку текста, имеют квадратные углы и не имеют стебля, указывающего на инструмент.

Подсказки отслеживания, поддерживаемые версии 4.70 распространенных элементов управления, динамически изменяют положение на экране. Быстро обновляя позицию, эти элементы управления подсказками создают эффект плавного перемещения или "отслеживания". Это полезно, если вы хотите, чтобы текст подсказки следовал за положением указателя мыши при его перемещении. Для получения дополнительной информации о подсказках отслеживания и примере кода, демонстрирующего их создание, см. раздел Подсказки отслеживания.

Многострочные подсказки, которые также поддерживаются версией 4.70 общих элементов управления, отображают текст в более чем одной строке. Это полезно для отображения длинных сообщений. Дополнительные сведения и пример, показывающий, как создать многострочные подсказки, см. в Многострочные подсказки.

Всплывающие подсказки отображаются в коробке с округленными углами и стеблем, указывающим на инструмент. Они могут быть однострочные или многострочные. На следующем рисунке показана подсказка воздушных шаров со стеблем и прямоугольником в их позициях по умолчанию. Дополнительные сведения о подсказках воздушных шаров и примере, демонстрирующего их создание, см. в разделе Использование элементов управления подсказками.

Подсказка также может содержать текст заглавия и значок, как показано на рисунке ниже. Обратите внимание, что подсказка должна содержать текст; Если он содержит только текст заголовка, подсказка не отображается. Кроме того, значок не отображается, если нет заголовка.

Иногда текстовые строки обрезаются, так как они слишком длинны для отображения полностью в небольшом окне. Встроенные подсказки используются для отображения текста для объектов, которые были обрезаны, как, например, имя файла на следующем рисунке. Чтобы увидеть пример создания подсказок на месте, см. In-Place подсказки.

Курсор должен зависнуть на инструменте на некоторое время, чтобы появилась подсказка. Длительность этого времени ожидания по умолчанию управляется временем двойного щелчка пользователя и обычно составляет около половины секунды. Чтобы указать значение времени ожидания, отличное от стандартного, отправьте контролу подсказки сообщение TTM_SETDELAYTIME.

Создание элементов управления подсказками

Чтобы создать элемент управления подсказкой, вызовите CreateWindowEx и укажите класс окна TOOLTIPS_CLASS. Этот класс регистрируется при загрузке библиотеки DLL общего элемента управления. Чтобы убедиться, что эта библиотека DLL загружена, включите в приложение функцию InitCommonControlsEx. Необходимо явно определить элемент управления подсказкой как самый верхний. В противном случае он может быть перекрыт родительским окном. В следующем фрагменте кода показано, как создать элемент управления подсказкой.

HWND hwndTip = CreateWindowEx(NULL, TOOLTIPS_CLASS, NULL,
                            WS_POPUP | TTS_NOPREFIX | TTS_ALWAYSTIP,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            hwndParent, NULL, hinstMyDll,
                            NULL);

SetWindowPos(hwndTip, HWND_TOPMOST,0, 0, 0, 0,
             SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE);

Процедура окна для элемента управления подсказками автоматически задает размер, положение и видимость элемента управления. Высота окна подсказки зависит от высоты шрифта, выбранного в контексте устройства для элемента управления подсказки. Ширина зависит от длины строки, которая в данный момент находится в окне подсказки.

Активация элементов управления подсказками

Элемент управления подсказками может быть активным или неактивным. Если он активен, текст подсказки появляется, когда указатель мыши находится на инструменте. Если он неактивен, текст подсказки не отображается, даже если указатель находится на инструменте. Сообщение TTM_ACTIVATE активирует и деактивирует управление всплывающими подсказками.

Вспомогательные инструменты

Элемент управления подсказками может поддерживать любое количество инструментов. Для поддержки определенного средства, необходимо зарегистрировать средство в элементе управления подсказками, отправив сообщение элементу управления TTM_ADDTOOL. Сообщение содержит адрес структуры TOOLINFO, которая предоставляет информацию, необходимую элементу управления подсказки для отображения текста инструмента. Элемент uID структуры TOOLINFO определяется приложением. При каждом добавлении средства приложение предоставляет уникальный идентификатор. Требуется элемент cbSize структуры TOOLINFO, и он должен указать размер структуры.

Элемент управления подсказкой поддерживает средства, реализованные как окна (например, дочерние окна или окна управления), а также прямоугольные области в клиентской области окна. При добавлении инструмента, реализованного в виде прямоугольной области, член hwnd структуры TOOLINFO должен указать дескриптор окна, содержащего эту область, а член rect должен указать клиентские координаты ограничивающего прямоугольника этой области. Кроме того, член uID должен указать идентификатор, заданный приложением для средства.

При добавлении инструмента, реализованного в виде окна, элемент uID в структуре TOOLINFO должен содержать дескриптор окна инструмента. Кроме того, элемент uFlags должен указать значение TTF_IDISHWND, которое указывает элементу управления подсказки интерпретировать элемент uID в качестве дескриптора окна.

Отображение текста

При добавлении инструмента в элемент управления подсказки lpszText член структуры TOOLINFO должен указать адрес строки, отображаемой для средства. После добавления инструмента можно изменить текст с помощью сообщения TTM_UPDATETIPTEXT.

Если слово с высоким порядком lpszText равно нулю, слово с низким порядком должно быть идентификатором строкового ресурса. Если элемент управления подсказками нуждается в тексте, система загружает указанный строковый ресурс из экземпляра приложения, определяемого элементом структуры TOOLINFO.

Если указать значение LPSTR_TEXTCALLBACK в члене lpszText, элемент управления подсказкой уведомляет окно, указанное в члене hwnd структуры TOOLINFO, когда ему нужно отображать текст для инструмента. Элемент управления подсказки отправляет код уведомления TTN_GETDISPINFO в окно. Сообщение содержит адрес структуры NMTTDISPINFO, которая содержит дескриптор окна, а также идентификатор, определенный приложением для средства. Окно проверяет структуру, чтобы определить инструмент, для которого требуется текст, и заполняет соответствующие элементы структуры сведениями, необходимыми элементу управления подсказки для отображения строки.

Заметка

Максимальная длина стандартного текста подсказки составляет 80 символов. Дополнительные сведения см. в структуре NMTTDISPINFO. Текст многострочной подсказки может быть длиннее.

 

Многие приложения создают панели инструментов, содержащие инструменты, соответствующие командам меню. Для таких инструментов удобно, чтобы контрол всплывающих подсказок отображал тот же текст, что и соответствующий элемент меню. Система автоматически удаляет символы акселерации в виде амперсанда (&) из всех строк, которые передаются в элемент управления подсказкой, и обрывает строку на первом символе табуляции (\t), если только элемент управления не имеет стиля TTS_NOPREFIX.

Чтобы получить текст для средства, используйте сообщение TTM_GETTEXT.

Обмен сообщениями и уведомлением

Текст подсказки обычно отображается при наведении указателя мыши на область, обычно прямоугольник, определенный средством, например элементом управления кнопкой. Однако Microsoft Windows отправляет только сообщения, связанные с мышью, в окно, содержащее указатель, а не сам элемент управления подсказки. Сведения, связанные с мышью, должны быть переданы в элемент управления подсказки, чтобы он отображал текст подсказки в соответствующее время и место.

Вы можете автоматически передавать сообщения, если:

• Этот инструмент является элементом управления или определяется как прямоугольник в структуре TOOLINFO.
• Окно, связанное с инструментом, находится в том же потоке, что и элемент управления подсказки.

Если выполнены эти два условия, установите флаг TTF_SUBCLASS в элементе uFlags член структуры TOOL INFO средства при добавлении средства в элемент управления подсказки с TTM_ADDTOOL. Затем необходимые сообщения мыши будут автоматически передаваться в элемент управления подсказкой.

Установка TTF_SUBCLASS для перенаправления сообщений мыши в элемент управления является достаточной для большинства целей. Однако он не будет работать в тех случаях, когда нет прямого подключения между элементом управления подсказкой и окном инструмента. Например, если средство реализуется как прямоугольная область в окне, определяемом приложением, процедура окна получает сообщения мыши. Настройка TTF_SUBCLASS достаточно, для обеспечения их передачи в элемент управления. Однако если средство реализуется как системное окно, сообщения мыши отправляются в это окно и не доступны напрямую приложению. В этом случае необходимо либо подклассить окно, либо использовать перехватчик сообщения для доступа к сообщениям мыши. Затем необходимо явно передать сообщения мыши элементу управления подсказками с помощью TTM_RELAYEVENT. Пример использования TTM_RELAYEVENTсм. в разделе Tracking Tooltips.

Когда элемент управления подсказки получает сообщение WM_MOUSEMOVE, определяет, находится ли указатель мыши в ограничивающем прямоугольнике инструмента. Если это так, элемент управления всплывающей подсказкой задает таймер. В конце интервала времени ожидания элемент управления подсказки проверяет положение указателя, чтобы узнать, перемещен ли он. Если это не так, элемент управления подсказки извлекает текст для инструмента и отображает подсказку. Элемент управления всплывающей подсказки продолжает отображать окно до тех пор, пока он не получит сообщение о отпускании или нажатии кнопки, или пока сообщение WM_MOUSEMOVE не укажет, что указатель перемещен за пределы ограничивающего прямоугольника инструмента.

Элемент управления подсказки фактически имеет три временных интервала ожидания, связанных с ним. Начальная длительность — это время, когда указатель мыши должен оставаться в ограничивающем прямоугольнике инструмента перед отображением окна подсказки. Длительность повторного отображения — это длина задержки, прежде чем последующие окна подсказки отображаются при переходе указателя с одного средства на другое. Длительность всплывающего окна — это время, когда окно подсказки по-прежнему отображается до его скрытия. То есть, если указатель остается стационарным в ограничивающем прямоугольнике после отображения окна подсказки, окно подсказки автоматически скрывается в конце всплывающего окна. Вы можете настроить все сроки ожидания с помощью сообщения TTM_SETDELAYTIME.

Если приложение включает инструмент, реализованный как прямоугольная область, и размер или положение элемента управления изменяется, приложение может использовать сообщение TTM_NEWTOOLRECT, чтобы сообщить об изменении в управлении подсказкой. Приложению не нужно сообщать об изменениях размера и положения для инструмента, реализованного в виде окна, так как элемент управления подсказки использует дескриптор окна средства для определения того, находится ли указатель мыши на инструменте, а не ограничивающий прямоугольник средства.

Когда подсказка собирается отобразиться, элемент управления подсказкой отправляет окну владельца код уведомления TTN_SHOW. Окно владельца получает код уведомления TTN_POP, когда подсказка собирается скрыться. Каждый код уведомления отправляется в контексте сообщения WM_NOTIFY.

Тестирование попаданий

Сообщение TTM_HITTEST позволяет получить сведения, которые элемент управления подсказки хранит о инструменте, занимающем определённую точку. Сообщение включает структуру TTHITTESTINFO, в которой содержится дескриптор окна, координаты точки и адрес структуры TOOLINFO. Элемент управления подсказки определяет, занимает ли инструмент точку и, если это делает, заполняет TOOLINFO сведениями о инструменте.

Обработка сообщений по умолчанию

В следующей таблице описываются сообщения, обрабатываемые процедурой окна для элемента управления подсказками.

Сообщение	Описание
WM_CREATE	Гарантирует, что элемент управления подсказкой имеет оконные стили WS_EX_TOOLWINDOW и WS_POPUP. Он также выделяет память и инициализирует внутренние переменные.
WM_DESTROY	Освобождает ресурсы, выделенные для элемента управления подсказками.
WM_GETFONT	Возвращает дескриптор шрифта, который элемент управления всплывающей подсказкой будет использовать для отображения текста.
WM_MOUSEMOVE	Скрывает окно подсказки.
WM_PAINT	Рисует окно подсказки.
WM_SETFONT	Задает дескриптор шрифта, который элемент управления всплывающими подсказками будет использовать для отображения текста.
WM_TIMER	Скрывает окно подсказки, если средство изменило положение или указатель мыши перемещен за пределы инструмента. В противном случае показывается окно подсказки.
WM_WININICHANGE	Сбрасывает внутренние переменные, основанные на системных метриках.