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

Статья
08/27/2023

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

Синтаксис

BOOL TextOutA(
  [in] HDC    hdc,
  [in] int    x,
  [in] int    y,
  [in] LPCSTR lpString,
  [in] int    c
);

Параметры

[in] hdc

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

[in] x

Координата X (в логических координатах) точки отсчета, которую система использует для выравнивания строки.

[in] y

Координата Y в логических координатах точки отсчета, которую система использует для выравнивания строки.

[in] lpString

Указатель на отрисовываемую строку. Строка не обязательно должна заканчиваться с нуля, так как cchString указывает длину строки.

[in] c

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

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

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение.

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

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

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

Когда функция TextOut помещается в скобку пути, система создает путь для текста TrueType, который включает каждый символ и его поле символов. Созданная область представляет собой символьное поле за вычетом текста, а не самого текста. Вы можете получить область, заключенную в контур текста TrueType, установив для фонового режима прозрачный, прежде чем помещать функцию TextOut в скобку пути. Ниже приведен пример кода, демонстрирующий эту процедуру.


// Obtain the window's client rectangle 
GetClientRect(hwnd, &r);

// THE FIX: by setting the background mode 
// to transparent, the region is the text itself 
// SetBkMode(hdc, TRANSPARENT); 

// Bracket begin a path 
BeginPath(hdc);

// Send some text out into the world 
TCHAR text[ ] = "Defenestration can be hazardous";
TextOut(hdc,r.left,r.top,text, ARRAYSIZE(text));

// Bracket end a path 
EndPath(hdc);

// Derive a region from that path 
SelectClipPath(hdc, RGN_AND);

// This generates the same result as SelectClipPath() 
// SelectClipRgn(hdc, PathToRegion(hdc)); 

// Fill the region with grayness 
FillRect(hdc, &r, GetStockObject(GRAY_BRUSH));

Примеры

Пример см. в разделе Перечисление установленных шрифтов.

Примечание

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	wingdi.h (включая Windows.h)
Библиотека	Gdi32.lib
DLL	Gdi32.dll