Função GetTextExtentExPointA (wingdi.h)

A função GetTextExtentExPoint recupera o número de caracteres em uma cadeia de caracteres especificada que caberá dentro de um espaço especificado e preenche uma matriz com a extensão de texto para cada um desses caracteres. (Uma extensão de texto é a distância entre o início do espaço e um caractere que caberá no espaço.) Essas informações são úteis para cálculos de encapsulamento de palavras.

Sintaxe

BOOL GetTextExtentExPointA(
  [in]  HDC    hdc,
  [in]  LPCSTR lpszString,
  [in]  int    cchString,
  [in]  int    nMaxExtent,
  [out] LPINT  lpnFit,
  [out] LPINT  lpnDx,
  [out] LPSIZE lpSize
);

Parâmetros

[in] hdc

Um identificador para o contexto do dispositivo.

[in] lpszString

Um ponteiro para a cadeia de caracteres terminada em nulo para a qual as extensões devem ser recuperadas.

[in] cchString

O número de caracteres na cadeia de caracteres apontada pelo parâmetro lpszStr . Para uma chamada ANSI, ela especifica o comprimento da cadeia de caracteres em bytes e, para um Unicode, especifica o comprimento da cadeia de caracteres em WORDs. Observe que, para a função ANSI, os caracteres nas páginas de código SBCS recebem um byte cada, enquanto a maioria dos caracteres nas páginas de código DBCS leva dois bytes; para a função Unicode, os caracteres Unicode definidos no momento (aqueles no Plano Multilíngue Básico (BMP)) são um WORD, enquanto os substitutos Unicode são dois WORDs.

[in] nMaxExtent

A largura máxima permitida, em unidades lógicas, da cadeia de caracteres formatada.

[out] lpnFit

Um ponteiro para um inteiro que recebe uma contagem do número máximo de caracteres que caberá no espaço especificado pelo parâmetro nMaxExtent . Quando o parâmetro lpnFit é NULL, o parâmetro nMaxExtent é ignorado.

[out] lpnDx

Um ponteiro para uma matriz de inteiros que recebe extensões parciais de cadeia de caracteres. Cada elemento na matriz fornece a distância, em unidades lógicas, entre o início da cadeia de caracteres e um dos caracteres que se ajusta ao espaço especificado pelo parâmetro nMaxExtent . Essa matriz deve ter pelo menos tantos elementos quanto os caracteres especificados pelo parâmetro cchString porque toda a matriz é usada internamente. A função preenche a matriz com extensões válidas para quantos caracteres forem especificados pelo parâmetro lpnFit . Todos os valores no restante da matriz devem ser ignorados. Se alpDx for NULL, a função não computa larguras parciais de cadeia de caracteres.

Para scripts complexos, em que uma sequência de caracteres pode ser representada por qualquer número de glifos, os valores na matriz alpDx até o número especificado pelo parâmetro lpnFit correspondem um para um com pontos de código. Novamente, você deve ignorar o restante dos valores na matriz alpDx .

[out] lpSize

Um ponteiro para uma estrutura SIZE que recebe as dimensões da cadeia de caracteres, em unidades lógicas. Esse parâmetro não pode ser NULL.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero.

Comentários

Se os parâmetros lpnFit e alpDx forem NULL, chamar a função GetTextExtentExPoint será equivalente a chamar a função GetTextExtentPoint .

Para a versão ANSI de GetTextExtentExPoint, a matriz lpDx tem o mesmo número de valores INT que há bytes em lpString. Os valores INT que correspondem aos dois bytes de um caractere DBCS são cada uma a extensão de todo o caractere composto.

Observe que os valores alpDx para GetTextExtentExPoint não são os mesmos que os valores lpDx para ExtTextOut. Para usar os valores alpDx no lpDx, primeiro você deve processá-los.

Quando essa função retorna a extensão de texto, ela pressupõe que o texto é horizontal, ou seja, que o escape é sempre 0. Isso é verdadeiro para as medidas horizontais e verticais do texto. Mesmo que você use uma fonte que especifique um escape diferente de zero, essa função não usará o ângulo enquanto computa a extensão do texto. O aplicativo deve convertê-lo explicitamente. No entanto, quando o modo gráfico é definido como GM_ADVANCED e a orientação do caractere está a 90 graus da orientação de impressão, os valores retornados por essa função não seguem essa regra. Quando a orientação do caractere e a orientação de impressão correspondem a uma determinada cadeia de caracteres, essa função retorna as dimensões da cadeia de caracteres na estrutura SIZE como { cx : 116, cy : 18 }. Quando a orientação do caractere e a orientação de impressão estão a 90 graus de distância para a mesma cadeia de caracteres, essa função retorna as dimensões da cadeia de caracteres na estrutura SIZE como { cx : 18, cy : 116 }.

Essa função retorna a extensão de cada caractere sucessivo em uma cadeia de caracteres. Quando eles são arredondados para unidades lógicas, você obtém resultados diferentes do que é retornado do GetCharWidth, que retorna a largura de cada caractere individual arredondado para unidades lógicas.

Observação

O cabeçalho wingdi.h define GetTextExtentExPoint como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	wingdi.h (inclua Windows.h)
Biblioteca	Gdi32.lib
DLL	Gdi32.dll

Confira também

Funções de fonte e texto

Visão geral de fontes e texto

GetTextExtentPoint

SIZE