Функция 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)
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.