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

Статья
2023-06-08

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

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

Синтаксис

int DrawTextW(
  [in]      HDC     hdc,
  [in, out] LPCWSTR 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	Рисует без обрезки. При использовании DT_NOCLIP drawText выполняется несколько быстрее.
DT_NOFULLWIDTHCHARBREAK	Предотвращает разрыв строки в DBCS (двухуровневая строка символов), чтобы правило разбиения строк было эквивалентно строкам SBCS. Например, его можно использовать в окнах на корейском языке для повышения удобочитаемости меток значков. Это значение не действует, если не указано DT_WORDBREAK.
DT_NOPREFIX	Выключает обработку символов префикса. Обычно DrawText интерпретирует символ мнемонического префикса & как директиву для подчеркивания следующего символа, а символы префикса && как директиву для печати одного &. При указании 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.

Примечание

Заголовок winuser.h определяет DrawText как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	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)