Usando um editor de método de entrada em um jogo

Observação

Este artigo detalha o trabalho com o IME (Editor de Método de Entrada) do Windows XP. Foram feitas alterações no IME para Windows Vista que não são totalmente detalhadas neste artigo. Para obter mais informações sobre alterações no IME para Windows Vista, consulte Editores de Método de Entrada (IME) no Windows Vista – Uma exibição Ever-Expanding de internacionalização no Portal de Computação e Desenvolvimento Global da Microsoft.

Um IME (editor de método de entrada) é um programa que permite entrada de texto fácil usando um teclado padrão para idiomas do Leste Asiático, como chinês, japonês, coreano e outros idiomas com caracteres complexos. Por exemplo, com IMEs, um usuário pode digitar caracteres complexos em um processador de palavras ou um jogador de um jogo online multijogador maciço pode conversar com amigos em caracteres complexos.

Este artigo explica como você pode implementar um controle de edição de IME básico em um aplicativo Microsoft DirectX em tela inteira. Os aplicativos que aproveitam o DXUT obtêm automaticamente a funcionalidade IME. Para aplicativos que não fazem uso da estrutura, este artigo descreve como adicionar suporte ao IME a um controle de edição.

Conteúdo:

• Comportamento padrão do IME
• Usando IMEs com DXUT
• Substituindo o comportamento padrão do IME
• Funções
• Mensagens
• Exemplos
  • CHT IME versão 4.2, 4.3 e 4.4
  • CHT IME versão 5.0
  • CHT IME versão 5.1, 5.2 e CHS IME versão 5.3
  • CHS IME versão 4.1
  • CHS IME versão 4.2
• Mensagens IME
  • WM_INPUTLANGCHANGE
  • WM_IME_STARTCOMPOSITION
  • WM_IME_COMPOSITION
  • WM_IME_ENDCOMPOSITION
  • WM_IME_NOTIFY
• Renderização
  • Indicador de Localidade de Entrada
  • Janela de Composição
  • Leitura e janelas candidatas
• Limitações
• Informações do Registro
• Apêndice A: versões do CHT por sistema operacional
• Mais informações
• GetReadingString
• ShowReadingWindow

Comportamento padrão do IME

IMEs mapeiam a entrada de teclado para componentes fonéticos ou outros elementos de linguagem específicos a um idioma selecionado. Em um cenário típico, o usuário digita chaves que representam a pronúncia de um caractere complexo. Se o IME reconhecer a pronúncia como válida, ele apresentará ao usuário uma lista de candidatos de palavra ou frase da qual o usuário pode selecionar uma escolha final. Em seguida, a palavra escolhida é enviada ao aplicativo por meio de uma série de mensagens do Microsoft Windows WM_CHAR . Como o IME funciona em um nível abaixo do aplicativo interceptando a entrada do teclado, a presença de um IME é transparente para o aplicativo. Quase todos os aplicativos do Windows podem aproveitar prontamente os IMEs sem estar cientes de sua existência e sem exigir codificação especial.

Um IME típico exibe várias janelas para orientar o usuário por meio da entrada de caracteres, conforme mostrado nos exemplos a seguir.

Tipo de janela	Descrição	Saída do IME
a. Janela de Leitura	Contém pressionamentos de tecla do teclado; normalmente é alterado após cada pressionamento de tecla.	cadeia de caracteres de leitura
B. Janela de Composição	Contém a coleção de caracteres que o usuário compôs com o IME. Esses caracteres são desenhados pelo IME na parte superior do aplicativo. Quando o usuário notifica o IME de que a cadeia de caracteres de composição é satisfatória, o IME envia a cadeia de caracteres de composição para o aplicativo por meio de uma série de mensagens WM_CHAR.	cadeia de caracteres de composição
C. Janela Candidato	Quando o usuário insere uma pronúncia válida, o IME exibe uma lista de caracteres candidatos que correspondem à pronúncia determinada. Em seguida, o usuário seleciona o caractere pretendido nessa lista e o IME adiciona esse caractere à exibição Janela de Composição.	o próximo caractere na cadeia de caracteres de composição
D. Indicador de Localidade de Entrada	Mostra o idioma que o usuário selecionou para entrada de teclado. Esse indicador é inserido na barra de tarefas do Windows. O idioma de entrada pode ser selecionado abrindo as Opções Regionais e de Idioma Painel de Controle e, em seguida, clicando em Detalhes na guia Idiomas.	-

Usando IMEs com DXUT

No DXUT, a classe CDXUTIMEEditBox implementa a funcionalidade IME. Essa classe é derivada da classe CDXUTEditBox, o controle de edição básico fornecido pela estrutura. CDXUTIMEEditBox estende esse controle de edição para dar suporte a IMEs substituindo os métodos CDXUTIMEEditBox. As classes foram projetadas dessa maneira para ajudar os desenvolvedores a aprender o que precisam usar da estrutura para implementar o suporte ao IME em seus próprios controles de edição. O restante deste tópico explica como a estrutura, e CDXUTIMEEditBox em particular, substitui um controle de edição básico para implementar a funcionalidade do IME.

A maioria das variáveis específicas do IME em CDXUTIMEEditBox são declaradas como estáticas, pois muitos buffers de IME e estados são específicos para o processo. Por exemplo, um processo tem apenas um buffer para a cadeia de caracteres de composição. Mesmo que o processo tenha dez controles de edição, todos eles compartilharão o mesmo buffer de cadeia de caracteres de composição. O buffer de cadeia de caracteres de composição para CDXUTIMEEditBox é, portanto, estático, impedindo que o aplicativo ocupasse espaço de memória desnecessário.

CDXUTIMEEditBox é implementado no seguinte código DXUT:

(Raiz do SDK)\Samples\C++\Common\DXUTgui.cpp

Substituindo o comportamento padrão do IME

Normalmente, um IME usa procedimentos padrão do Windows para criar uma janela (consulte Usando o Windows). Em circunstâncias normais, isso produz resultados satisfatórios. No entanto, quando o aplicativo é apresentado no modo de tela inteira, como é comum para jogos, as janelas padrão não funcionam mais e podem não ser exibidas na parte superior do aplicativo. Para superar esse problema, o aplicativo deve desenhar as próprias janelas do IME em vez de depender do Windows para executar essa tarefa.

Quando o comportamento de criação da janela IME padrão não fornece o que um aplicativo requer, o aplicativo pode substituir o tratamento da janela do IME. Um aplicativo pode conseguir isso processando mensagens relacionadas ao IME e chamando a API do Gerenciador de Métodos de Entrada (IMM).

Quando um usuário interage com um IME para inserir caracteres complexos, o IMM envia mensagens para o aplicativo para notificá-lo de eventos importantes, como iniciar uma composição ou mostrar a janela candidata. Um aplicativo normalmente ignora essas mensagens e as passa para o manipulador de mensagens padrão, o que faz com que o IME as manipule. Quando o aplicativo, em vez do manipulador padrão, manipula as mensagens, ele controla exatamente o que acontece em cada um dos eventos IME. Muitas vezes, o manipulador de mensagens recupera o conteúdo das várias janelas IME chamando a API do IMM. Depois que o aplicativo tiver essas informações, ele poderá desenhar corretamente as próprias janelas IME quando precisar renderizar para a exibição.

Funções

Um IME precisa obter a cadeia de caracteres de leitura, ocultar a janela de leitura e obter a orientação da janela de leitura. Esta tabela mostra as funcionalidades por versão do IME:

	Obtendo a cadeia de caracteres de leitura	Ocultar janela de leitura	Orientação da janela de leitura
Antes da versão 6.0	a. Lendo dados privados do IME de Acesso à Janela diretamente. Confira "Estrutura 4"	Interceptar mensagens privadas do IME. Confira "3 mensagens"	Examine as informações do Registro. Confira "5 Informações do Registro"
Após a versão 6.0	GetReadingString	ShowReadingWindow	GetReadingString

Mensagens

As mensagens a seguir não precisam ser processadas para um IME mais recente que implemente ShowReadingWindow().

As mensagens a seguir são interceptadas pelo manipulador de mensagens do aplicativo (ou seja, elas não são passadas para DefWindowProc) para impedir que a janela de leitura apareça.

Msg == WM_IME_NOTIFY
wParam == IMN_PRIVATE
lParam == 1, 2 (CHT IME version 4.2, 4.3 and 4.4 / CHS IME 4.1 and 4.2)
lParam == 16, 17, 26, 27, 28 (CHT IME version 5.0, 5.1, 5.2 / CHS IME 5.3)

Exemplos

Os exemplos a seguir ilustram como obter informações de cadeia de caracteres de leitura do IME mais antigo que não tem GetReadingString(). O código gera as seguintes saídas:

Saída	Descrição
DWORD dwlen	Comprimento da cadeia de caracteres de leitura.
DWERR DWORD	Índice do caractere de erro.
LPWSTR wstr	Ponteiro para a cadeia de caracteres de leitura.
Unicode BOOL	Se for true, a cadeia de caracteres de leitura estará no formato Unicode. Caso contrário, ele está no formato multibyte.

CHT IME versão 4.2, 4.3 e 4.4

LPINPUTCONTEXT lpIMC = _ImmLockIMC(himc);
LPBYTE p = *(LPBYTE *)((LPBYTE)_ImmLockIMCC(lpIMC->hPrivate) + 24);
if (!p) break;
dwlen = *(DWORD *)(p + 7*4 + 32*4);
dwerr = *(DWORD *)(p + 8*4 + 32*4);
wstr = (WCHAR *)(p + 56);
unicode = TRUE;

CHT IME versão 5.0

LPINPUTCONTEXT lpIMC = _ImmLockIMC(himc);
LPBYTE p = *(LPBYTE *)((LPBYTE)_ImmLockIMCC(lpIMC->hPrivate) + 3*4);
if (!p) break;
p = *(LPBYTE *)((LPBYTE)p + 1*4 + 5*4 + 4*2 );
if (!p) break;
dwlen = *(DWORD *)(p + 1*4 + (16*2+2*4) + 5*4 + 16);
dwerr = *(DWORD *)(p + 1*4 + (16*2+2*4) + 5*4 + 16 + 1*4);
wstr = (WCHAR *)(p + 1*4 + (16*2+2*4) + 5*4);
unicode = FALSE;

CHT IME versão 5.1, 5.2 e CHS IME versão 5.3

LPINPUTCONTEXT lpIMC = _ImmLockIMC(himc);
LPBYTE p = *(LPBYTE *)((LPBYTE)_ImmLockIMCC(lpIMC->hPrivate) + 4);
if (!p) break;
p = *(LPBYTE *)((LPBYTE)p + 1*4 + 5*4); 
if (!p) break;
dwlen = *(DWORD *)(p + 1*4 + (16*2+2*4) + 5*4 + 16 * 2);
dwerr = *(DWORD *)(p + 1*4 + (16*2+2*4) + 5*4 + 16 * 2 + 1*4);
wstr  = (WCHAR *) (p + 1*4 + (16*2+2*4) + 5*4);
unicode = TRUE;

CHS IME versão 4.1

// GetImeId(1) returns VS_FIXEDFILEINFO:: dwProductVersionLS of IME file
int offset = ( GetImeId( 1 ) >= 0x00000002 ) ? 8 : 7;
LPINPUTCONTEXT lpIMC = _ImmLockIMC(himc);
BYTE p = *(LPBYTE *)((LPBYTE)_ImmLockIMCC(lpIMC->hPrivate) + offset * 4);
if (!p) break;
dwlen = *(DWORD *)(p + 7*4 + 16*2*4);
dwerr = *(DWORD *)(p + 8*4 + 16*2*4);
dwerr = min(dwerr, dwlen);
wstr = (WCHAR *)(p + 6*4 + 16*2*1);
unicode = TRUE;

CHS IME versão 4.2

int nTcharSize = IsNT() ? sizeof(WCHAR) : sizeof(char);
LPINPUTCONTEXT lpIMC = _ImmLockIMC(himc);
BYTE p = *(LPBYTE *)((LPBYTE)_ImmLockIMCC(lpIMC->hPrivate) + 1*4 + 1*4 + 6*4);
if (!p) break;
dwlen = *(DWORD *)(p + 1*4 + (16*2+2*4) + 5*4 + 16 * nTcharSize);
dwerr = *(DWORD *)(p + 1*4 + (16*2+2*4) + 5*4 + 16 * nTcharSize + 1*4);
wstr  = (WCHAR *) (p + 1*4 + (16*2+2*4) + 5*4);
unicode = IsNT() ? TRUE : FALSE;

Mensagens IME

Um aplicativo de tela inteira deve lidar corretamente com as seguintes mensagens relacionadas ao IME:

WM_INPUTLANGCHANGE

O IMM envia uma mensagem WM_INPUTLANGCHANGE para a janela ativa de um aplicativo depois que a localidade de entrada é alterada pelo usuário com uma combinação de teclas (geralmente ALT+SHIFT) ou com o indicador de localidade de entrada na barra de tarefas ou na barra de idiomas. A barra de idiomas é um controle na tela com o qual o usuário pode configurar um serviço de texto. (Confira Como mostrar a barra de idiomas.) A captura de tela a seguir mostra uma lista de seleção de idioma exibida quando o usuário clica no indicador de localidade.

Quando o IMM envia uma mensagem WM_INPUTLANGCHANGE, CDXUTIMEEditBox deve executar várias tarefas importantes:

1. O método GetKeyboardLayout é chamado para retornar o ID (identificador de localidade de entrada) para o thread do aplicativo. A classe CDXUTIMEEditBox salva essa ID em sua variável de membro estático s_hklCurrent para uso posterior. É importante que o aplicativo conheça a localidade de entrada atual, pois o IME de cada idioma tem seu próprio comportamento distinto. O desenvolvedor pode precisar fornecer um código diferente para diferentes localidades de entrada.
2. CDXUTIMEEditBox inicializa uma cadeia de caracteres a ser exibida no indicador de idioma da caixa de edição. Esse indicador pode exibir o idioma de entrada ativo quando o aplicativo está em execução no modo de tela inteira e nem a barra de tarefas nem a barra de idiomas estão visíveis.
3. O método ImmGetConversionStatus é chamado para indicar se a localidade de entrada está no modo de conversão nativo ou não nativo. O modo de conversão nativa permite que o usuário insira texto no idioma escolhido. O modo de conversão não nativo faz com que o teclado atue como um teclado padrão em inglês. É importante dar ao usuário uma indicação visual sobre em que tipo de modo de conversão o IME está, para que o usuário possa saber facilmente quais caracteres esperar ao pressionar uma chave. CDXUTIMEEditBox fornece essa indicação visual com uma cor de indicador de linguagem. Quando a localidade de entrada usa um IME com modo de conversão nativo, a classe CDXUTIMEEditBox desenha o texto do indicador com a cor definida pelo parâmetro m_IndicatorImeColor. Quando o IME está no modo de conversão não nativo ou nenhum IME é usado, a classe desenha o texto do indicador com a cor definida pelo parâmetro m_IndicatorEngColor.
4. CDXUTIMEEditBox verifica a localidade de entrada e define a variável de membro estático s_bInsertOnType como TRUE para coreano e FALSE para todos os outros idiomas. Esse sinalizador é necessário devido aos diferentes comportamentos de IMEs coreanos e todos os outros IMEs. Ao inserir caracteres em idiomas diferentes do coreano, o texto inserido pelo usuário é exibido na janela de composição e o usuário pode alterar livremente o conteúdo da cadeia de caracteres de composição. O usuário pressiona a tecla ENTER quando satisfeito com a cadeia de caracteres de composição e a cadeia de caracteres de composição é enviada ao aplicativo como uma série de mensagens WM_CHAR. No entanto, em IMEs coreanos, quando um usuário pressiona uma tecla para inserir texto, um caractere é enviado imediatamente para o aplicativo. Quando o usuário pressiona posteriormente mais teclas para modificar esse caractere inicial, o caractere na caixa de edição é alterado para refletir a entrada adicional do usuário. Essencialmente, o usuário está redigindo caracteres na caixa de edição. Esses dois comportamentos são diferentes o suficiente para que CDXUTIMEEditBox precise codificar para cada um deles especificamente.
5. O método membro estático SetupImeApi é chamado para recuperar endereços de duas funções do módulo IME: GetReadingString e ShowReadingWindow. Se essas funções existirem, ShowReadingWindow será chamado para ocultar a janela de leitura padrão para esse IME. Como o aplicativo renderiza a própria janela de leitura, ele notifica o IME para desabilitar o desenho da janela de leitura padrão para que ela não interfira na renderização em tela inteira.

O IMM envia uma mensagem WM_IME_SETCONTEXT quando uma janela do aplicativo é ativada. O parâmetro lParam dessa mensagem contém um sinalizador que indica ao IME quais janelas devem ser desenhadas e quais não devem ser desenhadas. Como o aplicativo está manipulando todo o desenho, ele não precisa do IME para desenhar nenhuma das janelas IME. Portanto, o manipulador de mensagens do aplicativo simplesmente define lParam como 0 e retorna.

Para que os aplicativos deem suporte ao IME, o processamento especial é necessário para a mensagem relacionada ao IME WM_IME_SETCONTEXT. Como o Windows normalmente envia essa mensagem para o aplicativo antes de chamar o método PanoramaInitialize(), o Panorama não tem a chance de processar a interface do usuário para mostrar janelas de lista de candidatos.

O snippet de código a seguir especifica aos aplicativos do Windows que não exibam nenhuma interface do usuário associada à janela de lista de candidatos, permitindo que o Panorama manipule especificamente essa interface do usuário.

case WM_IME_SETCONTEXT:
         lParam = 0;
    lRet = DefWindowProc(hWnd, msg, wParam, lParam);
    break;
    //... more message processing
    return lRet;

WM_IME_STARTCOMPOSITION

O IMM envia uma mensagem WM_IME_STARTCOMPOSITION para o aplicativo quando uma composição do IME está prestes a começar como resultado de pressionamentos de tecla pelo usuário. Se o IME usar a janela de composição, ele exibirá a cadeia de caracteres de composição atual em uma janela de composição. CDXUTIMEEditBox manipula essa mensagem executando duas tarefas:

1. CDXUTIMEEditBox limpa o buffer de cadeia de caracteres de composição e o buffer de atributo. Esses buffers são membros estáticos de CDXUTIMEEditBox.
2. CDXUTIMEEditBox define o s_bHideCaret variável de membro estático como TRUE. Esse membro, definido na classe base CDXUTEditBox, controla se o cursor na caixa de edição deve ser desenhado quando a caixa de edição é renderizada. A janela de composição funciona de forma semelhante a uma caixa de edição com texto e cursor. Para evitar confusão quando a janela de composição está visível, a caixa de edição oculta seu cursor para que apenas um cursor fique visível por vez.

WM_IME_COMPOSITION

O IMM envia uma mensagem WM_IME_COMPOSITION para o aplicativo quando o usuário insere um pressionamento de tecla para alterar a cadeia de caracteres de composição. O valor de lParam indica que tipo de informação o aplicativo pode recuperar do Gerenciador de Métodos de Entrada (IMM). O aplicativo deve recuperar as informações disponíveis chamando ImmGetCompositionString e, em seguida, deve salvar as informações em seu buffer privado para que ele possa renderizar os elementos IME mais tarde.

CDXUTIMEEditBox verifica e recupera os seguintes dados de cadeia de caracteres de composição:

WM_IME_COMPOSITION valor do sinalizador lParam	Dados	Descrição
GCS_COMPATTR	Atributo de composição	Esse atributo contém informações como o status de cada caractere na cadeia de caracteres de composição (por exemplo, convertido ou não convertido). Essas informações são necessárias porque CDXUTIMEEditBox colore os caracteres de cadeia de caracteres de composição de forma diferente com base em seus atributos.
GCS_COMPCLAUSE	Informações da cláusula de composição	Essas informações de cláusula são usadas quando o IME japonês está ativo. Quando uma cadeia de caracteres de composição japonesa é convertida, os caracteres podem ser agrupados como uma cláusula que é convertida em uma única entidade. Quando o usuário move o cursor, CDXUTIMEEditBox usa essas informações para realçar a cláusula inteira, em vez de apenas um único caractere dentro da cláusula .
GCS_COMPSTR	Cadeia de caracteres de composição	Essa cadeia de caracteres é a cadeia de caracteres atualizada que está sendo composta pelo usuário. Essa também é a cadeia de caracteres exibida na janela de composição.
GCS_CURSORPOS	Posição do cursor de composição	A janela de composição implementa um cursor, semelhante ao cursor em uma caixa de edição. O aplicativo pode recuperar a posição do cursor ao processar a mensagem WM_IME_COMPOSITION para desenhar o cursor corretamente.
GCS_RESULTSTR	Cadeia de caracteres de resultado	A cadeia de caracteres de resultado está disponível quando o usuário está prestes a concluir o processo de composição. Essa cadeia de caracteres deve ser recuperada e os caracteres devem ser enviados para a caixa de edição.

WM_IME_ENDCOMPOSITION

O IMM envia uma mensagem WM_IME_ENDCOMPOSITION para o aplicativo quando a operação de composição do IME está terminando. Isso pode ocorrer quando o usuário pressiona a tecla ENTER para aprovar a cadeia de caracteres de composição ou a tecla ESC para cancelar a composição. CDXUTIMEEditBox manipula essa mensagem definindo o buffer de cadeia de caracteres de composição como vazio. Em seguida, ele define s_bHideCaret como FALSE porque a janela de composição está fechada e o cursor na caixa de edição deve ficar visível novamente.

O manipulador de mensagens CDXUTIMEEditBox também define s_bShowReadingWindow como FALSE. Esse sinalizador controla se a classe desenha a janela de leitura quando a caixa de edição se renderiza, portanto, deve ser definida como FALSE quando uma composição termina.

WM_IME_NOTIFY

O IMM envia uma mensagem WM_IME_NOTIFY para o aplicativo sempre que uma janela do IME é alterada. Um aplicativo que manipula o desenho das janelas IME deve processar essa mensagem para que ele esteja ciente de qualquer atualização para o conteúdo da janela. O wParam indica o comando ou a alteração que está ocorrendo. CDXUTIMEEditBox manipula os seguintes comandos:

Comando IME	Descrição
IMN_SETOPENSTATUS	Esse atributo contém informações como o status de cada caractere na cadeia de caracteres de composição (por exemplo, convertido ou não convertido). Essas informações são necessárias porque CDXUTIMEEditBox colore os caracteres de cadeia de caracteres de composição de forma diferente com base em seus atributos.
/ IMN_OPENCANDIDATE IMN_CHANGECANDIDATE	Enviado para o aplicativo quando a janela candidata está prestes a ser aberta ou atualizada, respectivamente. A janela candidata é aberta quando um usuário deseja alterar a opção de texto convertida. A janela é atualizada quando um usuário move o indicador de seleção ou altera a página. CDXUTIMEEditBox usa um manipulador de mensagens para ambos os comandos porque as tarefas necessárias são exatamente as mesmas: CDXUTIMEEditBox define o membro bShowWindow da estrutura de lista de candidatos s_CandList como TRUE para indicar que a janela candidata precisa ser desenhada durante a renderização do quadro. CDXUTIMEEditBox recupera a lista de candidatos chamando ImmGetCandidateList, primeiro para obter o tamanho do buffer necessário e, em seguida, novamente para obter os dados reais. A estrutura de lista de candidatos privados s_CandList é inicializada com os dados candidatos recuperados. As cadeias de caracteres candidatas são armazenadas como uma matriz de cadeias de caracteres. O índice da entrada selecionada, bem como o índice da página, é salvo. CDXUTIMEEditBox verifica se o estilo da janela candidata é vertical ou horizontal. Se o estilo da janela for horizontal, um buffer de cadeia de caracteres adicional, o membro HoriCand de s_CandList, deverá ser inicializado com todas as cadeias de caracteres candidatas, com caracteres de espaço inseridos entre todas as cadeias de caracteres adjacentes. Ao renderizar uma janela de candidato vertical, as cadeias de caracteres candidatas individuais são desenhadas uma de cada vez, com as coordenadas y incrementadas para cada cadeia de caracteres. No entanto, essa cadeia de caracteres HoriCand deve ser usada ao renderizar uma janela candidata horizontal, pois o caractere de espaço é a melhor maneira de separar duas cadeias de caracteres adjacentes na mesma linha.
IMN_CLOSECANDIDATE	Enviado para o aplicativo quando uma janela candidata está prestes a ser fechada. Isso acontece quando um usuário faz uma seleção da lista de candidatos. CDXUTIMEEditBox manipula esse comando definindo o sinalizador visível da janela candidata como FALSE e, em seguida, limpando o buffer de cadeia de caracteres candidato.
IMN_PRIVATE	Enviado ao aplicativo quando o IME atualizou sua cadeia de caracteres de leitura como resultado da digitação ou remoção de caracteres do usuário. O aplicativo deve recuperar a cadeia de caracteres de leitura e salvá-la para renderização. CDXUTIMEEditBox tem dois métodos para recuperar a cadeia de caracteres de leitura, com base em como as cadeias de caracteres de leitura têm suporte no IME: Se o IME der suporte à função GetReadingString, GetReadingString será chamado para recuperar a cadeia de caracteres de leitura. Se o IME não implementar GetReadingString, CDXUTIMEEditBox recuperará a cadeia de caracteres de leitura do conteúdo de contexto de entrada.

Renderização

A renderização dos elementos e janelas do IME é simples. CDXUTIMEEditBox permite que a classe base seja renderizada primeiro porque as janelas IME devem aparecer na parte superior do controle de edição. Depois que a caixa de edição base é renderizada, CDXUTIMEEditBox verifica o sinalizador de visibilidade de cada janela IME (indicador, composição, candidato e janela de leitura) e desenha a janela se ela deve estar visível. Consulte Comportamento padrão do IME para obter descrições dos diferentes tipos de janela do IME.

Indicador de Localidade de Entrada

O indicador de localidade de entrada é renderizado antes de qualquer outra janela IME porque é um elemento que sempre é exibido. Portanto, ele deve aparecer abaixo de outras janelas IME. CDXUTIMEEditBox renderiza o indicador chamando o método RenderIndicator, no qual a cor da fonte do indicador é determinada examinando o s_ImeState variável estática, que reflete o modo de conversão de IME atual. Quando o IME está habilitado e a conversão nativa está ativa, o método usa m_IndicatorImeColor como a cor do indicador. Se o IME estiver desabilitado ou estiver no modo de conversão não nativo, m_IndicatorImeColor será usado para desenhar o texto do indicador. Por padrão, a janela indicadora em si é desenhada à direita da caixa de edição. Os aplicativos podem alterar esse comportamento substituindo o método RenderIndicator.

A figura a seguir mostra as diferentes aparências de um indicador de localidade de entrada para inglês, japonês no modo de conversão alfanumérica e japonês no modo de conversão nativa:

Janela de Composição

O desenho da janela de composição é tratado no método RenderComposition de CDXUTIMEEditBox. A janela de composição flutua acima da caixa de edição. Ele deve ser desenhado na posição do cursor do controle de edição subjacente. CDXUTIMEEditBox manipula a renderização da seguinte maneira:

1. Toda a cadeia de caracteres de composição é desenhada usando as cores de cadeia de caracteres de composição padrão.
2. Caracteres com determinados atributos especiais devem ser desenhados em cores diferentes, portanto, CDXUTIMEEditBox examina os caracteres da cadeia de caracteres de composição e inspeciona o atributo de cadeia de caracteres. Se o atributo chamar cores diferentes, o caractere será desenhado novamente com as cores apropriadas.
3. O cursor da janela de composição é desenhado para concluir a renderização.

O cursor deve piscar para IMEs coreanos, mas não deve para outros IMEs. RenderComposition determina se o cursor deve ser visível com base nos valores do temporizador quando o IME coreano é usado.

Leitura e janelas candidatas

As janelas de leitura e candidata são renderizadas pelo mesmo método CDXUTIMEEditBox, RenderCandidateReadingWindow. Ambas as janelas contêm uma matriz de cadeias de caracteres para layout vertical ou uma única cadeia de caracteres no caso de layout horizontal. A maior parte do código em RenderCandidateReadingWindow é usada para posicionar a janela para que nenhuma parte da janela fique fora da janela do aplicativo e seja recortada.

Limitações

Às vezes, os IMEs contêm recursos avançados para melhorar a facilidade de entrada de texto. Alguns dos recursos encontrados em IMEs mais recentes são mostrados nos números a seguir. Esses recursos avançados não estão presentes no DXUT. Implementar o suporte para esses recursos avançados pode ser desafiador porque não há nenhuma interface definida para obter as informações necessárias dos IMEs.

IME chinês tradicional avançado com lista de candidatos expandidos:

IME japonês avançado com algumas entradas candidatas que contêm texto adicional para descrever seus significados:

IME coreano avançado que inclui um sistema de reconhecimento de manuscrito:

Informações do Registro

As informações do Registro a seguir são verificadas para determinar a orientação da janela de leitura, quando o IME atual é o CHT New Phonetic mais antigo que não implementa GetReadingString().

Chave	Valor
HKCU\software\microsoft\windows\currentversion\IME_Name	mapeamento de teclado

Em que: IME_Name será MSTCIPH se a versão do arquivo IME for 5.1 ou posterior; caso contrário, IME_Name é TINTLGNT.

A orientação da janela de leitura será horizontal se:

• O IME é a versão 5.0 e o valor de mapeamento de teclado é 0x22 ou 0x23
• O IME é a versão 5.1 ou versão 5.2 e o valor de mapeamento de teclado é 0x22, 0x23 ou 0x24.

Se nenhuma das condições for atendida, a janela de leitura será vertical.

Apêndice A: versões do CHT por sistema operacional

Sistema operacional	Versão do IME do CHT
Windows 98	4.2
Windows 2000	4.3
unknown	4.4
Windows ME	5,0
Office XP	5.1
Windows XP	5.2
Download autônomo da Web	6,0

Mais informações

Para obter informações adicionais, consulte o seguinte:

• Instalar e usar editores de método de entrada
• Exibição de Texto Internacional
• O Consórcio Unicode
• Desenvolvendo software internacional. Dr. Internacional. 2º ed. Redmond, WA: Microsoft Press, 2003.

GetReadingString

Obtém informações de cadeia de caracteres de leitura.

Parâmetros

Himc

[in] Contexto de entrada.

uReadingBufLen

[in] Comprimento de lpwReadingBuf, no WCHAR. Se for zero, significa o comprimento do buffer de leitura de consulta.

lpwReadingBuf

[out] Retornar cadeia de caracteres de leitura (não fim zero).

pnErrorIndex

[out] Retornar o índice de caractere de erro na cadeia de caracteres de leitura se houver.

pfIsVertical

[out] Se for TRUE, a leitura da interface do usuário será vertical. Caso contrário, puMaxReadingLen horizontal.

puMaxReadingLen

[out] O comprimento da interface do usuário de leitura. O comprimento máximo de leitura não é fixo; ele depende não apenas do layout do teclado, mas também do modo de entrada (por exemplo, código interno, entrada alternativa).

Valores de retorno

O comprimento da cadeia de caracteres de leitura.

Comentários

Se o valor retornado for maior que o valor de uReadingBufLen, todos os parâmetros de saída serão indefinidos.

Essa função é implementada no CHT IME 6.0 ou posterior e pode ser adquirida por GetProcAddress em um identificador de módulo IME; O identificador do módulo IME pode ser adquirido por ImmGetIMEFileName e LoadLibrary.

Requirements

Cabeçalho

Declarado em Imm.h.

Biblioteca de Importação

Use Imm.lib.

ShowReadingWindow

Mostrar (ou ocultar) a janela de leitura.

Parâmetros

Himc

[in] Contexto de entrada.

Bshow

[in] Defina como TRUE para mostrar a janela de leitura (ou FALSE para ocultá-la).

Valores de retorno

Comentários

Retornará TRUE se tiver êxito ou FALSE, caso contrário.

Requirements

Cabeçalho

Declarado em Imm.h.

Biblioteca de Importação

Use Imm.lib.