Функция ExtTextOutW (wingdi.h)

Статья
11/20/2024

Функция ExtTextOut рисует текст с помощью выбранного в данный момент шрифта, цвета фона и цвета текста. При необходимости можно указать измерения, используемые для обрезки, непрозрачности или обоих.

Синтаксис

BOOL ExtTextOutW(
  [in] HDC        hdc,
  [in] int        x,
  [in] int        y,
  [in] UINT       options,
  [in] const RECT *lprect,
  [in] LPCWSTR    lpString,
  [in] UINT       c,
  [in] const INT  *lpDx
);

Параметры

[in] hdc

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

[in] x

Координата x в логических координатах эталонной точки, используемой для размещения строки.

[in] y

Координата y в логических координатах эталонной точки, используемой для размещения строки.

[in] options

Указывает, как использовать прямоугольник, определенный приложением. Этот параметр может быть одним или несколькими из следующих значений.

Ценность	Значение
ETO_CLIPPED	Текст будет обрезан прямоугольником.
ETO_GLYPH_INDEX	Массив lpString относится к массиву, возвращенному из GetCharacterPlacement и должен быть проанализирован непосредственно GDI, так как не требуется дополнительная обработка на языке. Индексирование глифов применяется только к шрифтам TrueType, но флаг можно использовать для растровых и векторных шрифтов, чтобы указать, что дополнительная обработка языка не требуется, а GDI должна обрабатывать строку напрямую. Обратите внимание, что все индексы глифов являются 16-разрядными значениями, даже если строка считается массивом 8-разрядных значений для растровых шрифтов. Для ExtTextOutW индексы глифов сохраняются в метафайл. Однако для отображения правильных символов метафайла необходимо воспроизвести обратно с помощью того же шрифта. Для ExtTextOutA индексы глифов не сохраняются.
ETO_IGNORELANGUAGE	Зарезервировано для использования системы. Если приложение задает этот флаг, он теряет поддержку международных сценариев, и в некоторых случаях он не отображает текст вообще.
ETO_NUMERICSLATIN	Для отображения чисел используйте европейские цифры.
ETO_NUMERICSLOCAL	Чтобы отобразить числа, используйте цифры, соответствующие языковому стандарту.
ETO_OPAQUE	Текущий цвет фона должен использоваться для заполнения прямоугольника.
ETO_PDY	Если это задано, массив, на который указывает lpDx, содержит пары значений. Первое значение каждой пары — это, как обычно, расстояние между источниками смежных ячеек символов, но вторым значением является смещение вдоль вертикального направления шрифта.
ETO_RTLREADING	выпуск Windows на Ближнем Востоке: Если это значение указано, а в контексте устройства выбран иврит или арабский шрифт, строка выводится с помощью порядка чтения справа налево. Если это значение не указано, строка выводится в левом порядке вправо. Этот же эффект можно достичь, задав значение TA_RTLREADING в SetTextAlign. Это значение сохраняется для обратной совместимости.

Значения ETO_GLYPH_INDEX и ETO_RTLREADING нельзя использовать вместе. Так как ETO_GLYPH_INDEX означает, что все языковые обработки завершены, функция игнорирует флаг ETO_RTLREADING, если он также указан.

[in] lprect

Указатель на необязательную структуру RECT, указывающую измерения в логических координатах прямоугольника, используемого для вырезки, непрозрачности или обоих элементов.

[in] lpString

Указатель на строку, указывающую нарисованный текст. Строка не должна быть завершена нулевой, так как cbCount указывает длину строки.

[in] c

Длина строки, на которую указывает lpString.

Это значение не может превышать 8192.

[in] lpDx

Указатель на необязательный массив значений, указывающий расстояние между источниками смежных ячеек символов. Например, lpDx[i] логические единицы разделяют источники ячеек символов i и ячейки символов i + 1.

Возвращаемое значение

Если строка рисуется, возвращаемое значение ненулевое. Однако если версия ANSI ExtTextOut вызывается с ETO_GLYPH_INDEX, функция возвращает TRUE даже если функция ничего не делает.

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

Замечания

Текущие параметры выравнивания текста для указанного контекста устройства определяют, как эталонная точка используется для размещения текста. Параметры выравнивания текста извлекаются путем вызова функции GetTextAlign. Параметры выравнивания текста изменяются путем вызова функции SetTextAlign. Для выравнивания текста можно использовать следующие значения. Только один флаг можно выбрать из тех, которые влияют на горизонтальное и вертикальное выравнивание. Кроме того, можно выбрать только один из двух флагов, которые изменяют текущую позицию.

Срок	Описание
TA_BASELINE	Эталонная точка будет находиться в базовой строке текста.
TA_BOTTOM	Эталонная точка будет находиться на нижнем краю ограничивающего прямоугольника.
TA_TOP	Эталонная точка будет находиться на верхнем крае ограничивающего прямоугольника.
TA_CENTER	Эталонная точка будет выровнена по горизонтали с центром ограничивающего прямоугольника.
TA_LEFT	Эталонная точка будет находиться в левом крае ограничивающего прямоугольника.
TA_RIGHT	Эталонная точка будет находиться в правом краю ограничивающего прямоугольника.
TA_NOUPDATECP	Текущая позиция не обновляется после каждого вызова вывода текста. Эталонная точка передается в функцию вывода текста.
TA_RTLREADING	выпуск Windows на Ближнем Востоке: текст расположен в правом левом порядке чтения, а не по умолчанию слева направо. Это применяется только в том случае, если шрифт, выбранный в контексте устройства, является ивритом или арабским.
TA_UPDATECP	Текущая позиция обновляется после каждого вызова вывода текста. Текущая позиция используется в качестве эталонной точки.

Если параметр lpDx NULL, функция ExtTextOut использует интервал по умолчанию между символами. Источники символьных ячеек и содержимое массива, на которые указывает параметр lpDx, указываются в логических единицах. Источник ячейки символов определяется как левый верхний угол ячейки символа.

По умолчанию текущая позиция не используется или обновляется этой функцией. Однако приложение может вызывать функцию SetTextAlign с параметром fMode TA_UPDATECP, чтобы разрешить системе использовать и обновлять текущую позицию при каждом вызове приложения ExtTextOut для указанного контекста устройства. Если этот флаг задан, система игнорирует параметры X и Y при последующих вызовах ExtText Out.

Для версии ANSI ExtTextOutмассив lpDx имеет то же количество значений INT, что и байты в lpString. Для символов DBCS можно упорядочение dx в записи lpDx между байтами свинца и байтами следа, если сумма двух байтов добавляется к требуемому dxу. Для символов DBCS с версией Юникода ExtTextOutкаждый глиф Юникода получает одну запись pdx.

Обратите внимание, что значения alpDx из GetTextExtentExPoint не совпадают со значениями lpDx для ExtTextOut. Чтобы использовать значения alpDx в lpDx, необходимо сначала обработать их.

ExtTextOut будет использовать Uniscribe при необходимости, что приведет к резервному использованию шрифта. Флаг ETO_IGNORELANGUAGE будет препятствовать этому поведению и не должен передаваться.

Кроме того, ExtTextOut будет выполнять внутреннюю пакетную обработку вызовов перед переходом в режим ядра, уменьшая некоторые проблемы производительности при взвешивании использования PolyTextOut и ExtTextOut.

Кончик

ExtTextOut настоятельно рекомендуется по сравнению с PolyTextOut для современной разработки из-за его способности обрабатывать отображение различных языков.

Примеры

Пример см. в разделе "Настройка шрифтов для Menu-Item текстовых строк" в использование меню.

Заметка

Заголовок wingdi.h определяет ExtTextOut как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	wingdi.h (включая Windows.h)
библиотеки	Gdi32.lib
DLL	Gdi32.dll