Função GetTextExtentExPointA (wingdi.h)

A função GetTextExtentExPoint recupera o número de caracteres em uma cadeia de caracteres especificada que se ajustará a um espaço especificado e preencherá 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 apontado 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 levam um byte cada, enquanto a maioria dos caracteres nas páginas de código DBCS leva dois bytes; para a função Unicode, a maioria dos 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 permitido, 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 encaixa no 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 da 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 a 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 de retorno

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

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

Observações

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 um a extensão de todo o caractere composto.

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

Quando essa função retorna a extensão de texto, ela assume 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 especifica um escape diferente de zero, essa função não usa o ângulo enquanto calcula a extensão de 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 doGetCharWidth , que retorna a largura de cada caractere individual arredondado para unidades lógicas.

Requisitos

Consulte também

Funções de fonte e texto

fontes e visão geral de texto

getTextExtentPoint

tamanho do