Função GetCharacterPlacementA (wingdi.h)

Artigo
03/08/2023

A função GetCharacterPlacement recupera informações sobre uma cadeia de caracteres, como larguras de caractere, posicionamento de cursor, ordenação dentro da cadeia de caracteres e renderização de glifo. O tipo de informação retornada depende do parâmetro dwFlags e se baseia na fonte selecionada no momento no contexto de exibição especificado. A função copia as informações para a estrutura de GCP_RESULTS especificada ou para uma ou mais matrizes especificadas pela estrutura.

Embora essa função já tenha sido adequada para trabalhar com cadeias de caracteres, a necessidade de trabalhar com um número crescente de idiomas e scripts a tornou obsoleta. Ele foi substituído pela funcionalidade do módulo Uniscribe. Para obter mais informações, consulte Uniscribe.

É recomendável que um aplicativo use a função GetFontLanguageInfo para determinar se os valores GCP_DIACRITIC, GCP_DBCS, GCP_USEKERNING, GCP_LIGATE, GCP_REORDER, GCP_GLYPHSHAPE e GCP_KASHIDA são válidos para a fonte selecionada no momento. Se não for válido, GetCharacterPlacement ignorará o valor.

O valor GCP_NODIACRITICS não é mais definido e não deve ser usado.

Sintaxe

DWORD GetCharacterPlacementA(
  [in]      HDC            hdc,
  [in]      LPCSTR         lpString,
  [in]      int            nCount,
  [in]      int            nMexExtent,
  [in, out] LPGCP_RESULTSA lpResults,
  [in]      DWORD          dwFlags
);

Parâmetros

[in] hdc

Um identificador para o contexto do dispositivo.

[in] lpString

Um ponteiro para a cadeia de caracteres a ser processada. A cadeia de caracteres não precisa ser terminada em zero, pois nCount especifica o comprimento da cadeia de caracteres.

[in] nCount

O comprimento da cadeia de caracteres apontada por lpString.

[in] nMexExtent

A extensão máxima (em unidades lógicas) para a qual a cadeia de caracteres é processada. São ignorados os caracteres que, se processados, excederiam essa extensão. As computações para qualquer ordenação necessária ou matrizes de glifo se aplicam somente aos caracteres incluídos. Esse parâmetro será usado somente se o valor GCP_MAXEXTENT for especificado no parâmetro dwFlags . À medida que a função processa a cadeia de caracteres de entrada, cada caractere e sua extensão são adicionados à saída, extensão e outras matrizes somente se a extensão total ainda não tiver excedido o máximo. Depois que o limite for atingido, o processamento será interrompido.

[in, out] lpResults

Um ponteiro para uma estrutura GCP_RESULTS que recebe os resultados da função.

[in] dwFlags

Especifica como processar a cadeia de caracteres nas matrizes necessárias. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
GCP_CLASSIN	Especifica que a matriz lpClass contém classificações predefinidas para caracteres. As classificações podem ser as mesmas que na saída. Se a classificação específica de um caractere não for conhecida, o local correspondente na matriz deverá ser definido como zero. para obter mais informações sobre as classificações, consulte GCP_RESULTS. Isso só será útil se GetFontLanguageInfo retornar o sinalizador GCP_REORDER.
GCP_DIACRITIC	Determina como os diacríticos na cadeia de caracteres são tratados. Se esse valor não estiver definido, os diacríticos serão tratados como caracteres de largura zero. Por exemplo, uma cadeia de caracteres hebraica pode conter diacríticos, mas talvez você não queira exibi-las. Use GetFontLanguageInfo para determinar se uma fonte dá suporte a diacríticos. Se isso acontecer, você poderá usar ou não o sinalizador GCP_DIACRITIC na chamada para GetCharacterPlacement, dependendo das necessidades do aplicativo.
GCP_DISPLAYZWG	Para linguagens que precisam de reordenação ou formas de glifo diferentes, dependendo das posições dos caracteres dentro de uma palavra, caracteres não reproduzíveis geralmente aparecem na página de código. Por exemplo, na página de código hebraico, há marcadores da esquerda para a direita e da direita para a esquerda para ajudar a determinar o posicionamento final dos caracteres dentro das cadeias de caracteres de saída. Normalmente, eles não são exibidos e são removidos das matrizes lpGlyphs e lpDx . Você pode usar o sinalizador GCP_DISPLAYZWG para exibir esses caracteres.
GCP_GLYPHSHAPE	Especifica que alguns ou todos os caracteres na cadeia de caracteres devem ser exibidos usando formas diferentes das formas padrão definidas na fonte atualmente selecionada para a página de código atual. Alguns idiomas, como árabe, não podem dar suporte à criação de glifo, a menos que esse valor seja especificado. Como regra geral, se GetFontLanguageInfo retornar esse valor para uma cadeia de caracteres, esse valor deverá ser usado com GetCharacterPlacement.
GCP_JUSTIFY	Ajusta as extensões na matriz lpDx para que o comprimento da cadeia de caracteres seja o mesmo que nMaxExtent. GCP_JUSTIFY só pode ser usado em conjunto com GCP_MAXEXTENT.
GCP_KASHIDA	Use Kashidas, bem como, ou, em vez de, extensões ajustadas para modificar o comprimento da cadeia de caracteres para que ela seja igual ao valor especificado por nMaxExtent. Na matriz lpDx , um Kashida é indicado por um índice de justificativa negativa. GCP_KASHIDA só poderá ser usado em conjunto com GCP_JUSTIFY e somente se a fonte (e a linguagem) der suporte a Kashidas. Use GetFontLanguageInfo para determinar se a fonte atual dá suporte a Kashidas. Usar Kashidas para justificar a cadeia de caracteres pode fazer com que o número de glifos necessários seja maior que o número de caracteres na cadeia de caracteres de entrada. Por isso, quando Kashidas é usado, o aplicativo não pode assumir que definir as matrizes como o tamanho da cadeia de caracteres de entrada será suficiente. (O máximo possível será aproximadamente dxPageWidth/dxAveCharWidth, em que dxPageWidth é a largura do documento e dxAveCharWidth é a largura média do caractere, conforme retornado de uma chamada GetTextMetrics ). Observe que só porque GetFontLanguageInfo retorna o sinalizador GCP_KASHIDA não significa que ele precisa ser usado na chamada para GetCharacterPlacement, apenas que a opção está disponível.
GCP_LIGATE	Use ligações onde quer que os caracteres se ligam. Ocorre uma ligação em que um glifo é usado para dois ou mais caracteres. Por exemplo, as letras a e e podem se ligar a ?. Para que isso seja usado, no entanto, o suporte ao idioma e à fonte devem dar suporte aos glifos necessários (o exemplo não será processado por padrão em inglês). Use GetFontLanguageInfo para determinar se a fonte atual dá suporte à ligação. Se isso acontecer e um máximo específico for necessário para o número de caracteres que serão ligados, defina o número no primeiro elemento da matriz lpGlyphs . Se a ligação normal for necessária, defina esse valor como zero. Se GCP_LIGATE não for especificado, nenhuma ligação ocorrerá. Consulte GCP_RESULTS para obter mais informações. Se o valor GCP_REORDER geralmente for necessário para o conjunto de caracteres, mas não for especificado, a saída não terá sentido, a menos que a cadeia de caracteres que está sendo passada já esteja em ordenação visual (ou seja, o resultado que é colocado em lpGcpResults-lpOutString> em uma chamada para GetCharacterPlacement é a cadeia de caracteres de entrada de uma segunda chamada). Observe que só porque GetFontLanguageInfo retorna o sinalizador GCP_LIGATE não significa que ele precisa ser usado na chamada para GetCharacterPlacement, apenas que a opção está disponível.
GCP_MAXEXTENT	As extensões de computação da cadeia de caracteres somente desde que a extensão resultante, em unidades lógicas, não exceda os valores especificados pelo parâmetro nMaxExtent .
GCP_NEUTRALOVERRIDE	Somente determinados idiomas. Substitua o tratamento normal de neutros e trate-os como caracteres fortes que correspondem à ordem de leitura das cadeias de caracteres. Útil somente com o sinalizador GCP_REORDER.
GCP_NUMERICOVERRIDE	Somente determinados idiomas. Substitua o tratamento normal de numéricos e trate-os como caracteres fortes que correspondem à ordem de leitura das cadeias de caracteres. Útil somente com o sinalizador GCP_REORDER.
GCP_NUMERICSLATIN	Somente árabe/tailandês. Use glifos latinos padrão para números e substitua o padrão do sistema. Para determinar se essa opção está disponível no idioma da fonte, use GetStringTypeEx para ver se o idioma dá suporte a mais de um formato de número.
GCP_NUMERICSLOCAL	Somente árabe/tailandês. Use glifos locais para caracteres numéricos e substitua o padrão do sistema. Para determinar se essa opção está disponível no idioma da fonte, use GetStringTypeEx para ver se o idioma dá suporte a mais de um formato de número.
GCP_REORDER	Reordene a cadeia de caracteres. Use para idiomas que não são SBCS e ordem de leitura da esquerda para a direita. Se esse valor não for especificado, a cadeia de caracteres já estará em ordem de exibição. Se esse sinalizador for definido para idiomas semitas e a matriz lpClass for usada, os dois primeiros elementos da matriz serão usados para especificar a ordem de leitura além dos limites da cadeia de caracteres. GCP_CLASS_PREBOUNDRTL e GCP_CLASS_PREBOUNDLTR podem ser usados para definir a ordem. Se nenhuma ordem predefinida for necessária, defina os valores como zero. Esses valores poderão ser combinados com outros valores se o sinalizador GCPCLASSIN estiver definido. Se o valor GCP_REORDER não for especificado, o parâmetro lpString será usado para ser ordenado visualmente para linguagens em que isso é usado e os campos lpOutString e lpOrder serão ignorados. Use GetFontLanguageInfo para determinar se a fonte atual dá suporte à reordenação.
GCP_SYMSWAPOFF	Somente idiomas semitas. Especifica que os caracteres permutáveis não são redefinidos. Por exemplo, em uma cadeia de caracteres da direita para a esquerda, '(' e ')' não são invertidos.
GCP_USEKERNING	Use pares de kerning na fonte (se houver) ao criar as matrizes de larguras. Use GetFontLanguageInfo para determinar se a fonte atual dá suporte a pares de kerning. Observe que só porque GetFontLanguageInfo retorna o sinalizador GCP_USEKERNING não significa que ele precisa ser usado na chamada para GetCharacterPlacement, apenas que a opção está disponível. A maioria das fontes TrueType tem uma tabela de kerning, mas você não precisa usá-la.

O valor GCP_NODIACRITICS não é mais definido e não deve ser usado.

Retornar valor

Se a função for bem-sucedida, o valor retornado será a largura e a altura da cadeia de caracteres em unidades lógicas. A largura é a palavra de baixa ordem e a altura é a palavra de alta ordem.

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

Comentários

GetCharacterPlacement garante que um aplicativo possa processar o texto corretamente, independentemente da configuração internacional e do tipo de fontes disponíveis. Os aplicativos usam essa função antes de usar a função ExtTextOut e no lugar da função GetTextExtentPoint32 (e ocasionalmente no lugar das funções GetCharWidth32 e GetCharABCWidths ).

O uso de GetCharacterPlacement para recuperar o espaçamento entre caracteres e as matrizes de índice nem sempre é necessário, a menos que seja necessária justificativa ou kerning. Para fontes não latinas, os aplicativos podem melhorar a velocidade com que a função ExtTextOut renderiza o texto usando GetCharacterPlacement para recuperar o espaçamento entre caracteres e as matrizes de índice antes de chamar ExtTextOut. Isso é especialmente útil ao renderizar o mesmo texto repetidamente ou ao usar o espaçamento entre caracteres para posicionar o cursor. Se a matriz de saída lpGlyphs for usada na chamada para ExtTextOut, o sinalizador ETO_GLYPH_INDEX deverá ser definido.

GetCharacterPlacement verifica os membros lpOrder, lpDX, lpCaretPos, lpOutString e lpGlyphs da estrutura GCP_RESULTS e preenche as matrizes correspondentes se esses membros não estiverem definidos como NULL. Se GetCharacterPlacement não puder preencher uma matriz, ele definirá o membro correspondente como NULL. Para garantir a recuperação de informações válidas, o aplicativo é responsável por definir o membro como um endereço válido antes de chamar a função e verificar o valor do membro após a chamada. Se os valores GCP_JUSTIFY ou GCP_USEKERNING forem especificados, os membros lpDX e/ou lpCaretPos deverão ter endereços válidos.

Observe que os índices de glifo retornados em GCP_RESULTS.lpGlyphs são específicos para a fonte atual no contexto do dispositivo e só devem ser usados para desenhar texto no contexto do dispositivo enquanto essa fonte permanece selecionada.

Ao calcular a justificativa, se os caracteres à direita na cadeia de caracteres forem espaços, a função reduzirá o comprimento da cadeia de caracteres e removerá os espaços antes de calcular a justificativa. Se a matriz consistir apenas em espaços, a função retornará um erro.

ExtTextOut espera uma entrada lpDX para cada byte de uma cadeia de caracteres DBCS, enquanto GetCharacterPlacement atribui uma entrada lpDX para cada glifo. Para corrigir essa incompatibilidade ao usar essa combinação de funções, use GetGlyphIndices ou expanda a matriz lpDX com entradas de largura zero para o segundo byte correspondente de um par de bytes DBCS.

Se a largura lógica for menor que a largura do caractere à esquerda na cadeia de caracteres de entrada, GCP_RESULTS.nMaxFit retornará um valor inválido. Para esse caso, chame GetCharacterPlacement para índices de glifo e a matriz lpDX . Em seguida, use a matriz lpDX para fazer o cálculo de extensão usando a largura avançada de cada caractere, em que nMaxFit é o número de caracteres cujos índices de glifo avançam largura é menor que a largura do caractere à esquerda.

Observação

O cabeçalho wingdi.h define GetCharacterPlacement 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