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

Статья
2024-11-20

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

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

Синтаксис

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

Параметры

[in] hdc

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

[in, out] lpchText

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

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

[in] cchText

Длина строки в символах. Если cchText равно -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	Игнорирует символ префикса амперсанда (&) в тексте. Буква, следующая ниже, не будет подчеркиваться, но другие символы mnemonic-префикса по-прежнему обрабатываются. Пример: входная строка: "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-префикс & как директиву, чтобы подчеркнуть символ, который следует, и символы mnemonic-префикс && в качестве директивы для печати одного &. При указании 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 или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winuser.h (включая Windows.h)
библиотеки	User32.lib
DLL	User32.dll
набор API	ext-ms-win-ntuser-misc-l1-1-0 (представлено в Windows 8)