Поделиться через


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

Функция 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)

См. также раздел

DrawTextEx

Функции шрифта и текста

Общие сведения о шрифтах и тексте

GrayString

RECT

TabbedTextOut

TextOut