estrutura GCP_RESULTSA (wingdi.h)
A estrutura GCP_RESULTS contém informações sobre caracteres em uma cadeia de caracteres. Essa estrutura recebe os resultados da função GetCharacterPlacement . Para algumas linguagens, o primeiro elemento nas matrizes pode conter mais informações dependentes de idioma.
Sintaxe
typedef struct tagGCP_RESULTSA {
DWORD lStructSize;
LPSTR lpOutString;
UINT *lpOrder;
int *lpDx;
int *lpCaretPos;
LPSTR lpClass;
LPWSTR lpGlyphs;
UINT nGlyphs;
int nMaxFit;
} GCP_RESULTSA, *LPGCP_RESULTSA;
Membros
lStructSize
Especifica o tamanho, em bytes, da estrutura.
lpOutString
Um ponteiro para o buffer que recebe a cadeia de caracteres de saída ou é NULL se a cadeia de caracteres de saída não for necessária. A cadeia de caracteres de saída é uma versão da cadeia de caracteres original que está na ordem que será exibida em um dispositivo especificado. Normalmente, a cadeia de caracteres de saída é idêntica à cadeia de caracteres original, mas pode ser diferente se a cadeia de caracteres precisar ser reordenada e o sinalizador GCP_REORDER estiver definido ou se a cadeia de caracteres original exceder a extensão máxima e o sinalizador GCP_MAXEXTENT estiver definido.
lpOrder
Um ponteiro para a matriz que recebe índices de ordenação ou é NULL se os índices de ordenação não forem necessários. No entanto, seu significado depende dos outros elementos de GCP_RESULTS. Se os índices de glifo forem retornados, os índices serão para a matriz lpGlyphs ; se os índices de glifos não forem retornados e lpOrder for solicitado, os índices serão para lpOutString. Por exemplo, no último caso, o valor de lpOrder[i] é a posição de lpString[i] na cadeia de caracteres de saída lpOutString.
Normalmente, isso é usado quando GetFontLanguageInfo retorna o sinalizador GCP_REORDER, que indica que a cadeia de caracteres original precisa ser reordenada. Por exemplo, em hebraico, no qual o texto é executado da direita para a esquerda, a matriz lpOrder fornece os locais exatos de cada elemento na cadeia de caracteres original.
lpDx
Um ponteiro para a matriz que recebe as distâncias entre células de caractere adjacentes ou é NULL se essas distâncias não forem necessárias. Se a renderização do glifo for feita, as distâncias serão para os glifos e não para os caracteres, portanto, a matriz resultante poderá ser usada com a função ExtTextOut .
As distâncias nessa matriz estão em ordem de exibição. Para localizar a distância do caractere ina cadeia de caracteres original, use a matriz lpOrder da seguinte maneira:
width = lpDx[lpOrder[i]];
lpCaretPos
Um ponteiro para a matriz que recebe os valores de posição do cursor ou é NULL se as posições de cursor não forem necessárias. Cada valor especifica a posição do cursor imediatamente antes do caractere correspondente. Em alguns idiomas, a posição do cursor de cada caractere pode não estar imediatamente à esquerda do caractere. Por exemplo, em hebraico, em que o texto é executado da direita para a esquerda, a posição do cursor é à direita do caractere. Se a ordenação de glifo for concluída, lpCaretPos corresponderá à cadeia de caracteres original, não à cadeia de caracteres de saída. Isso significa que alguns valores adjacentes podem ser os mesmos.
Os valores nessa matriz estão na ordem de entrada. Para localizar o valor da posição do cursor para o caracterei na cadeia de caracteres original, use a matriz da seguinte maneira:
position = lpCaretPos[i];
lpClass
Um ponteiro para a matriz que contém e/ou recebe classificações de caracteres. Os valores indicam como definir caracteres na cadeia de caracteres e são semelhantes (mas não idênticos) aos valores CT_CTYPE2 retornados pela função GetStringTypeEx . Cada elemento da matriz pode ser definido como zero ou um dos valores a seguir.
Além disso, o seguinte pode ser usado ao fornecer valores na matriz lpClass com o sinalizador GCP_CLASSIN.
Para idiomas que usam o sinalizador GCP_REORDER, os valores a seguir também podem ser usados com o sinalizador GCP_CLASSIN. Ao contrário dos valores anteriores, que podem ser usados em qualquer lugar na matriz lpClass , todos os valores a seguir são usados somente no primeiro local da matriz. Todos combinam com outras classificações.
Observe que GCPCLASS_PREBOUNDLTR e GCPCLASS_PREBOUNDRTL são mutuamente exclusivos, assim como GCPCLASSPOSTBOUNDLTR e GCPCLASSPOSTBOUNDRTL.
Para forçar o layout de um caractere a ser executado de uma maneira específica, predefinir a classificação para o elemento de matriz correspondente; a função deixa essas classificações predefinidas inalteradas e calcula as classificações apenas para elementos de matriz que foram definidos como zero. As classificações predefinidas serão usadas somente se o sinalizador GCP_CLASSIN estiver definido e a matriz lpClass for fornecida.
Se GetFontLanguageInfo não retornar GCP_REORDER para a fonte atual, somente o valor GCPCLASS_LATIN será significativo.
lpGlyphs
Um ponteiro para a matriz que recebe os valores que identificam os glifos usados para renderizar a cadeia de caracteres ou é NULL se a renderização de glifo não for necessária. O número de glifos na matriz poderá ser menor que o número de caracteres na cadeia de caracteres original se a cadeia de caracteres contiver glifos ligadados. Além disso, se a reordenação for necessária, a ordem dos glifos poderá não ser sequencial.
Essa matriz será útil se mais de uma operação estiver sendo feita em uma cadeia de caracteres que tenha qualquer forma de ligação, kerning ou troca de pedidos. Usar os valores nessa matriz para operações subsequentes economiza o tempo necessário para gerar os índices de glifo a cada vez.
Essa matriz sempre contém índices de glifo e o valor de ETO_GLYPH_INDEX sempre deve ser usado quando essa matriz é usada com a função ExtTextOut .
Quando GCP_LIGATE é usado, você pode limitar o número de caracteres que serão ligatados juntos. (Em árabe, por exemplo, ligações de três caracteres são comuns). Isso é feito definindo o máximo necessário em lpGcpResults-lpGlyphs>[0]. Se nenhum máximo for necessário, você deverá definir esse campo como zero.
Para idiomas como árabe, em que GetFontLanguageInfo retorna o sinalizador GCP_GLYPHSHAPE, os glifos de um caractere serão diferentes dependendo se o caractere estiver no início, no meio ou no final de uma palavra. Normalmente, o primeiro caractere na cadeia de caracteres de entrada também será o primeiro caractere em uma palavra, e o último caractere na cadeia de caracteres de entrada será tratado como o último caractere em uma palavra. No entanto, se a cadeia de caracteres exibida for um subconjunto da cadeia de caracteres completa, como ao exibir uma seção de texto rolado, isso pode não ser verdadeiro. Nesses casos, é desejável forçar o primeiro ou o último caractere a ser moldado como não sendo formulários iniciais ou finais. Para fazer isso, novamente, o primeiro local na matriz lpGlyphs é usado executando uma operação OR do valor de ligação acima com os valores GCPGLYPH_LINKBEFORE e/ou GCPGLYPH_LINKAFTER. Por exemplo, um valor de GCPGLYPH_LINKBEFORE | 2 significa que as ligaturas de dois caracteres são o máximo necessário e o primeiro caractere na cadeia de caracteres deve ser tratado como se estivesse no meio de uma palavra.
nGlyphs
Na entrada, esse membro deve ser definido como o tamanho das matrizes apontadas pelos membros do ponteiro da matriz. Na saída, isso é definido como o número de glifos preenchidos nas matrizes de saída. Se a substituição de glifo não for necessária (ou seja, cada caractere de entrada mapeia para exatamente um glifo), esse membro será o mesmo que na entrada.
nMaxFit
O número de caracteres que se ajustam às extensões especificadas pelo parâmetro nMaxExtent da função GetCharacterPlacement . Se o valor GCP_MAXEXTENT ou GCP_JUSTIFY for definido, esse valor poderá ser menor que o número de caracteres na cadeia de caracteres original. Esse membro é definido independentemente de o valor GCP_MAXEXTENT ou GCP_JUSTIFY ser especificado. Ao contrário de nGlyphs, que especifica o número de glifos de saída, nMaxFit refere-se ao número de caracteres da cadeia de caracteres de entrada. Para idiomas latinos SBCS, isso será o mesmo.
Comentários
Se o lpGlyphs, lpOutString ou nenhum deles é necessário depende dos resultados da chamada GetFontLanguageInfo .
No caso de uma fonte para um idioma como inglês, em que nenhum dos sinalizadores GCP_DBCS, GCP_REORDER, GCP_GLYPHSHAPE, GCP_LIGATE, GCP_DIACRITIC ou GCP_KASHIDA são retornados, nenhuma das matrizes é necessária para a operação adequada. (Embora não seja necessário, eles ainda podem ser usados. Se a matriz lpOutString for usada, ela será exatamente igual à lpInputString passada para GetCharacterPlacement.) No entanto, observe que, se GCP_MAXEXTENT for usado, lpOutString conterá a cadeia de caracteres truncada se for usada, NÃO uma cópia exata do original.
No caso de fontes para idiomas como Hebraico, que TÊM reordenação, mas normalmente não têm formas de glifo extras, lpOutString deve ser usado. Isso dará a cadeia de caracteres na ordem legível pela tela. No entanto, a matriz lpGlyphs normalmente não é necessária. (Hebraico pode ter glifos extras, se a fonte for uma fonte TrueType/Open.)
No caso de idiomas como tailandês ou árabe, em que GetFontLanguageInfo retorna o sinalizador GCP_GLYPHSHAPE, o lpOutString dará a ordem de exibição legível da cadeia de caracteres passada para GetCharacterPlacement, mas os valores ainda serão os caracteres nãoformados. Para exibição adequada, a matriz lpGlyphs deve ser usada.
Observação
O cabeçalho wingdi.h define GCP_RESULTS 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] |
| Cabeçalho | wingdi.h (inclua Windows.h) |