Функция DrawText (winuser.h)

2023-07-21

Функция DrawText рисует отформатированный текст в указанном прямоугольнике. Он форматирует текст в соответствии с указанным методом (расширение вкладок, обоснование символов, разрывы линий и т. д.).

Чтобы указать дополнительные параметры форматирования, используйте функцию DrawTextEx .

Синтаксис

int DrawText(
  [in]      HDC     hdc,
  [in, out] LPCTSTR lpchText,
  [in]      int     cchText,
  [in, out] LPRECT  lprc,
  [in]      UINT    format
);

Параметры

[in] hdc

Дескриптор контекста устройства.

[in, out] lpchText

Указатель на строку, указывающую текст для рисования. Если параметр nCount имеет значение -1, строка должна быть завершена со значением NULL.

Если uFormat содержит DT_MODIFYSTRING, функция может добавить до четырех дополнительных символов в эту строку. Буфер, содержащий строку, должен быть достаточно большим, чтобы вместить эти дополнительные символы.

[in] cchText

Длина строки (в символах). Если значение nCount равно -1, то параметр lpchText считается указателем на строку, завершаемую null, и DrawText автоматически вычисляет число символов.

[in, out] lprc

Указатель на структуру RECT , содержащую прямоугольник (в логических координатах), в котором должен быть отформатирован текст.

[in] format

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

Значение	Значение
DT_BOTTOM	Оправдывает текст в нижней части прямоугольника. Это значение используется только с DT_SINGLELINE значением.
DT_CALCRECT	Определяет ширину и высоту прямоугольника. При наличии нескольких строк текста DrawText использует ширину прямоугольника, на который указывает параметр lpRect , и расширяет основание прямоугольника, чтобы привязать последнюю строку текста. Если наибольшее слово шире прямоугольника, ширина расширяется. Если текст меньше ширины прямоугольника, ширина уменьшается. Если текст содержит только одну строку, DrawText изменяет правую сторону прямоугольника таким образом, чтобы он граничит с последним символом в строке. В любом случае DrawText возвращает высоту отформатированного текста, но не рисует текст.
DT_CENTER	Центр текста по горизонтали в прямоугольнике.
DT_EDITCONTROL	Дублирует характеристики отображения текста многострочного элемента управления редактированием. В частности, средняя ширина символов вычисляется так же, как и для элемента управления редактированием, и функция не отображает частично видимую последнюю строку.
DT_END_ELLIPSIS	Для отображаемого текста, если конец строки не помещается в прямоугольник, он усекается и добавляется многоточие. Если слово, которое не находится в конце строки, выходит за рамки прямоугольника, оно усекается без многоточия. Строка не изменяется, если не указан флаг DT_MODIFYSTRING. Сравните с DT_PATH_ELLIPSIS и DT_WORD_ELLIPSIS.
DT_EXPANDTABS	Расширяет табуляцию. По умолчанию количество символов на шаг табуляции равно восьми. Значения DT_WORD_ELLIPSIS, DT_PATH_ELLIPSIS и DT_END_ELLIPSIS нельзя использовать со значением DT_EXPANDTABS.
DT_EXTERNALLEADING	Включает внешнее межстрочное расстояние шрифта в высоту строки. Как правило, внешний ввод не включается в высоту строки текста.
DT_HIDEPREFIX	Игнорирует символ префикса амперсанда (&) в тексте. Следующая буква не будет подчеркиваться, но другие мнемонические префиксы по-прежнему обрабатываются. Пример входная строка: "A&bc&&d" normal: "Abc&d" DT_HIDEPREFIX: "Abc&d" Сравните с DT_NOPREFIX и DT_PREFIXONLY.
DT_INTERNAL	Использует системный шрифт для вычисления размеров текста.
DT_LEFT	Выравнивает текст по левому краю.
DT_MODIFYSTRING	Изменяет указанную строку в соответствии с отображаемым текстом. Это значение не действует, если не указано DT_END_ELLIPSIS или DT_PATH_ELLIPSIS.
DT_NOCLIP	Рисует без обрезки. Функция DrawText выполняется несколько быстрее при использовании DT_NOCLIP.
DT_NOFULLWIDTHCHARBREAK	Предотвращает разрыв строки в DBCS (двухуровневая строка символов), чтобы правило разрыва строк было эквивалентно строкам SBCS. Например, его можно использовать в окнах на корейском языке для повышения удобочитаемости меток значков. Это значение не действует, если не указано DT_WORDBREAK.
DT_NOPREFIX	Выключает обработку символов префикса. Как правило, DrawText интерпретирует символ mnemonic-prefix & как директиву для подчеркивания следующего символа, а символы mnemonic-prefix && как директиву для печати одного &. При указании DT_NOPREFIX эта обработка отключается. Например, Пример входная строка: "A&bc&&d" normal: "Abc&d" DT_NOPREFIX: "A&bc&&d" Сравните с DT_HIDEPREFIX и DT_PREFIXONLY.
DT_PATH_ELLIPSIS	Для отображаемого текста заменяет символы в середине строки многоточием, чтобы результат помещался в указанный прямоугольник. Если строка содержит символы обратной косой черты (\), DT_PATH_ELLIPSIS сохраняет как можно больше текста после последней обратной косой черты. Строка не изменяется, если не указан флаг DT_MODIFYSTRING. Сравните с DT_END_ELLIPSIS и DT_WORD_ELLIPSIS.
DT_PREFIXONLY	Рисует только подчеркивание в позиции символа после символа амперсанда (&) префикса. Не рисует другие символы в строке. Например, Пример входная строка: "A&bc&&d"n normal: "Abc&d" DT_PREFIXONLY: " _ " Сравните с DT_HIDEPREFIX и DT_NOPREFIX.
DT_RIGHT	Выравнивает текст по правому краю.
DT_RTLREADING	Макет в порядке чтения справа налево для двунаправленного текста, если шрифт, выбранный в hdc , является ивритом или арабским шрифтом. Порядок чтения по умолчанию для всего текста — слева направо.
DT_SINGLELINE	Отображает текст только в одной строке. Возврат каретки и каналы строки не прерывают линию.
DT_TABSTOP	Задает позиции табуляции. Биты 15–8 (байт низкого порядка) параметра uFormat указывают количество символов для каждой вкладки. Число символов по умолчанию на вкладке — восемь. Значения DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP и DT_NOPREFIX нельзя использовать со значением DT_TABSTOP.
DT_TOP	Выравнивание текста до верхней части прямоугольника.
DT_VCENTER	Центр текста по вертикали. Это значение используется только с DT_SINGLELINE значением.
DT_WORDBREAK	Ломает слова. Линии автоматически разбиваются между словами, если слово выходит за край прямоугольника, заданного параметром lpRect . Последовательность перевода обратной строки каретки также разрывает линию. Если этот параметр не указан, выходные данные будут в одной строке.
DT_WORD_ELLIPSIS	Усекает любое слово, которое не помещается в прямоугольнике, и добавляет многоточие. Сравнение с DT_END_ELLIPSIS и DT_PATH_ELLIPSIS.

Возвращаемое значение

Если функция выполняется успешно, возвращаемым значением является высота текста в логических единицах. Если указан DT_VCENTER или DT_BOTTOM, возвращаемым значением является смещение от lpRect->top к нижней части нарисованного текста.

Если функция выполняется неудачно, возвращается нулевое значение.

Функция DrawText использует выбранный шрифт, цвет текста и цвет фона в контексте устройства для рисования текста. Если не используется формат DT_NOCLIP, DrawText вырезает текст, чтобы он не отображался за пределами указанного прямоугольника. Обратите внимание, что текст со значительным навесом может быть обрезан, например начальное "W" в текстовой строке или текст, назначаемого курсивом. Предполагается, что все форматирование состоит из нескольких строк, если не указан формат DT_SINGLELINE.

Если выделенный шрифт слишком велик для указанного прямоугольника, функция DrawText не пытается заменить шрифт меньшего размера.

Режим выравнивания текста для контекста устройства должен включать флаги TA_LEFT, TA_TOP и TA_NOUPDATECP.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winuser.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll
Набор API	ext-ms-win-ntuser-misc-l1-1-0 (представлено в Windows 8)