Функция DrawText

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

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

Синтаксис

int DrawText(
  HDC hDC,          // дескриптор контекста устройства
  LPCTSTR lpString, // текст для вывода
  int nCount,       // длина текста
  LPRECT lpRect,    // размеры поля форматирования
  UINT uFormat      // параметры вывода текста
);

Параметры

hDC

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

lpString
[in] Указатель на строку, которая устанавливает текст для вывода. Если параметр nCount равен - (минус)1, строка должна быть с нулевым символом в конце.

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

nCount
[in] Устанавливает длину строки. Для функции ANSI  - это число байтов (BYTE), а для функции Unicode, это является количеством слов (WORD). 
Обратите внимание! на то, что для функции ANSI, буквы в кодовых страницах SBCS (набора однобайтовых символов) занимают  по одному байту каждая, в то время как большинство букв в кодовых страницах DBCS (набора двухбайтовых символов)   занимает два байта; для функции Unicode наиболее правильное определение символов Unicode (это в Основной Многоязычной плоскости - Basic Multilingual Plane(BMP)) - одно слово (WORD), в то время как в заменителях Unicode - это два слова  (WORD). Если nCount  равен - (минус)1, то параметру lpString  присваивается роль указателя на символьную строку с нулем в конце, а функция DrawText вычисляет число символов автоматически.

Windows 95/98/Me: Величина этого числа не выходит за пределы 8192.

lpRect
[in/out] Указатель на структуру RECT, содержащую прямоугольник (в логических координатах), в котором текст, должен быть отформатирован.
uFormat
[in] Определяет метод форматирования текста. Этот параметр может быть один или несколько ниже перечисленных значений.

 

Значение Описание
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 Windows 2000/XP: Игнорирует амперсанд (&) префиксную букву в тексте. Буква, которая следует, не будет подчеркнута, но другие мнемонически-префиксные буквы все еще обрабатываются. Например:

введенная строка:    "A&bc&&d"
обычно:                    "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 Windows 98/Me, Windows 2000/XP: Не допускает перенос строки в DBCS (символьная строка двойной ширины), так, чтобы правило переноса строки было эквивалентно SBCS строкам. Например, это свойство может быть использовано в окнах с корейским языком, для большей удобочитаемости иероглифов. Это значение не имеет никакого действия, если флажок DT_WORDBREAK не установлен. 
DT_NOPREFIX Выключает обработку префиксных букв. Обычно, функция DrawText воспринимает мнемонически-префиксную букву & как директиву, чтобы подчеркнуть букву, которая следует после, а  мнемонически-префиксные символы && как директиву, чтобы печатать (отобразить на экране) единственную &. Устанавливая флажок DT_NOPREFIX, эта обработка отключается. Например,

введенная строка:   "A&bc&&d"
обычно:                   "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 Windows 2000/XP: Рисует только подчеркивание в позиции буквы, следующей за префиксным символом амперсанта (&) ). Не выводит никакие другие символы в строке. Например,

введенная строка:    "A&bc&&d"
обычно:                    "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; с верха до основания выводимого текста

Если функция завершается с ошибкой, величина возвращаемого значения - ноль.

Windows NT/2000/XP: Чтобы получить дополнительную информацию об ошибке, вызовите функцию GetLastError .

Замечания

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

Обратите внимание! на то, что тот текст с существенным выступом может быть отсечен, например, начальная "W" в текстовой строке или тексте, который находится в курсиве. Все форматирование предполагает, что имеется многочисленные строки, если формат DT_SINGLELINE не установлен.

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

Функция DrawText поддерживает только шрифты, где угол, под которым печатается шрифт и ориентация оба нулевые.

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

Windows 95/98/Me: DrawTextW поддерживается подпрограммой Microsoft Layer for Unicode. Чтобы использовать ее, Вы должны добавить некоторые файлы к вашему приложению, как изложено в требованиях этой подпрограммы для систем Windows 95/98/Me.

Код примера

Пример смотри  в статье Отображение ввода  данных с клавиатуры.

Смотри также

Обзор шрифты и текст, Функции, используемые шрифтами и текстом, DrawTextEx, GrayString, TabbedTextOut, TextOut, RECT

Размещение и совместимость DrawText

Windows. NET Server

Да

Windows XP

Да

Windows 2000

Да

Windows NT

Да

Windows Me

Да

Windows 98

Да

Windows 95

Да

Используемая библиотека

Gdi32.lib

Заголовочный файл

  

- объявлено в

Wingdi.h

- включено в

Windows.h

Unicode

Реализуется как версии Unicode и  ANSI в Windows NT /2000/XP.

Поддерживается также подпрограммой Microsoft Layer for Unicode

Замечания по платформе

Не имеется

 

Назад в оглавление
На главную страницу
На оглавление справки

Hosted by uCoz