Requisitos do IME (editor do método de entrada) personalizado

Estas diretrizes e requisitos podem ajudá-lo a desenvolver um IME (Editor de Método de Entrada) personalizado para ajudar um usuário a inserir texto em um idioma que não possa ser representado com facilidade em um teclado QWERTY padrão.

Para obter uma visão geral dos IMEs, consulte IME (Editor de Método de Entrada).

IME padrão

Um usuário pode selecionar qualquer um dos IMEs ativos (Configurações –> Hora e idioma –> Idioma –> Idiomas preferenciais –> Pacote de idiomas – Opções) para ser o IME padrão para o idioma preferido.

Selecione o teclado padrão na tela configurações de opções de idioma para o idioma preferido.

Importante

Não recomendamos gravar diretamente no Registro para definir o teclado padrão para seu IME personalizado.

Requisitos de compatibilidade.

A seguir estão os requisitos básicos de compatibilidade para um IME personalizado.

O IME deve ser compatível com aplicativos do Windows

Use a TSF (Estrutura de Serviços de Texto) para implementar IMEs. Antes, você tinha a opção de usar o IMM32 (Gerenciador de Método de Entrada) para serviços de entrada. Agora, o sistema bloqueia IMEs implementados usando o IMM32 (Gerenciador de Método de Entrada).

Quando um aplicativo é iniciado, o TSF carrega a DLL do IME para o IME selecionado pelo usuário no momento. Quando um IME é carregado, ele está sujeito às mesmas restrições de contêiner de aplicativo que o aplicativo. Por exemplo, um IME não poderá acessar a Internet se um aplicativo não tiver solicitado acesso à Internet em seu manifesto. Esse comportamento garante que os IMEs não possam violar contratos de segurança.

O TSF é o intermediário entre o aplicativo e seu IME. O TSF comunica eventos de entrada ao IME e recebe caracteres de entrada de volta do IME depois que o usuário seleciona um caractere.

Esse comportamento é o mesmo das versões anteriores do Windows, mas ser carregado em um aplicativo do Windows afeta os recursos potenciais de um IME.

Se o IME precisar fornecer funcionalidade ou interface do usuário diferente entre aplicativos do Windows e aplicativos da área de trabalho, verifique se a DLL carregada pelo TSF verifica em qual tipo de aplicativo ele está sendo carregado. Chame o método ITfThreadMgrEx::GetActiveFlags no IME e verifique o sinalizador TF_TMF_IMMERSIVEMODE para que o IME acione uma lógica de aplicativo diferente, dependendo do resultado.

Os aplicativos do Windows não oferecem suporte a IMEs de TTS (serviço de texto de tabela).

Observação

Algumas ferramentas para gerar IMEs TTS produzem IMEs que o Windows marca como malware.

O IME deve ser compatível com a bandeja do sistema

Não há barra de idiomas para hospedar ícones do IME. Em vez disso, um indicador de entrada é exibido na bandeja do sistema que indica a opção de entrada atual. O Indicador de Entrada mostra apenas o ícone de identidade visual do IME para indicar o IME em execução no momento. Além disso, há um ícone de modo IME que aparece à esquerda do ícone de identidade visual do IME para que os usuários executem a opção de modo IME mais usada, como ativar ou desativar o IME.

O Indicador de Entrada mostra o ícone de identidade visual e o ícone de modo do IME apenas para IMEs compatíveis. Os IMEs que não são compatíveis não têm o ícone de identidade visual e o ícone de modo exibidos na bandeja do sistema. Em vez disso, o indicador de entrada mostra a abreviação do idioma em vez do ícone de identidade visual do IME.

Armazene os ícones do IME em um arquivo DLL ou EXE, em vez de um arquivo .ico autônomo. O design dos ícones do IME deve seguir as diretrizes descritas na seção de diretrizes de design da interface do usuário a seguir.

Ícone de identidade visual do IME

O indicador de Entrada obtém o ícone de identidade visual do IME da DLL do IME usando a ID do recurso definida pelo IME quando ele foi registrado no sistema.

Ícone do modo IME

Alguns IMEs talvez precisem confiar no Indicador de Entrada exibido na bandeja do sistema para exibir o ícone do modo IME. Nesse caso, o IME passa o ícone do modo IME para o indicador de Entrada usando GUID_LBI_INPUTMODE.

Ao passar os ícones do modo IME para o Indicador de entrada na bandeja do sistema, o tamanho padrão do ícone do modo IME é de 16x16 pixels. O dimensionamento da interface do usuário segue o DPI.

Ao passar o ícone do modo IME para o Indicador de Entrada no UAC (Controle de Conta de Usuário na Área de Trabalho Protegida), o tamanho padrão do ícone do modo IME é de 20x20 pixels. O dimensionamento da interface do usuário para o ícone do modo IME no UAC segue o PPI.

O IME deve funcionar no contêiner de aplicativo

Algumas funções do IME são afetadas em um contêiner de aplicativo.

• Arquivos de dicionário – frequentemente, os IMEs têm arquivos de dicionário somente leitura para mapear a entrada de usuário para caracteres específicos. Para acessar esses arquivos de dentro de um contêiner de aplicativo, o IME deve colocá-los nos diretórios Arquivos de Programas ou Windows. Por padrão, esses diretórios podem ser lidos de um contêiner de aplicativo, para que os IMEs consigam acessar arquivos de dicionário armazenados nesses locais. Se o IME precisar armazenar o arquivo de dicionário em outro lugar, ele deverá manipular explicitamente as Listas de Controle de Acesso (ACL) dos arquivos de dicionário para permitir o acesso por meio de contêineres de aplicativos.
• Atualização da Internet - se o IME precisar atualizar seus dicionários usando dados da Internet, ele não poderá fazer isso de modo confiável dentro de um contêiner de aplicativo, porque o acesso à Internet nem sempre é permitido. Em vez disso, o IME deve executar um processo de área de trabalho separado que é responsável por atualizar os arquivos de dicionário com dados da Internet.
• Aprendizado instantâneo – se um IME estiver sendo executado em um contêiner de aplicativo com acesso à Internet, não haverá restrição sobre os pontos de extremidade com os quais o IME pode se comunicar. Nesse caso, um IME pode usar um servidor em nuvem para fornecer serviços de aprendizado em tempo real. Alguns IMEs fazem download e upload da entrada de usuário em tempo real, enquanto o usuário está digitando. Como o acesso à Internet não é garantido em um contêiner de aplicativo, isso nem sempre pode ser permitido.
• Compartilhamento de informações entre processos – os IMEs podem precisar compartilhar dados sobre as preferências de entrada do usuário entre aplicativos que estão em contêineres de aplicativos diferentes. Use um serviço Web para compartilhar dados entre aplicativos.

Importante

Se você tentar contornar as regras de segurança do contêiner de aplicativo, seu IME poderá ser tratado como malware e bloqueado.

IME e teclado virtual

O IME deve garantir que a interface do usuário do painel candidato e outros elementos da interface do usuário não sejam desenhados sob o teclado virtual. O teclado virtual é exibido em uma faixa de ordem z mais alta do que todos os aplicativos, e a interface do usuário do IME é exibida na mesma faixa de ordem z do aplicativo em que ele está ativo. Assim, o teclado virtual pode se sobrepor e ocultar a interface do usuário do IME. Na maioria dos casos, o aplicativo deve redimensionar sua janela para considerar o teclado virtual. Se um aplicativo não for redimensionado, o IME ainda poderá usar a API InputPane para obter a posição do teclado virtual. O IME consulta a propriedade Location ou registra um manipulador para os eventos Show e Hide do teclado virtual. O evento Show é gerado sempre que o usuário toca em um campo de edição, mesmo que o teclado virtual esteja sendo exibido no momento. O IME pode usar essa API para obter o espaço de tela usado pelo teclado virtual antes que o IME desenhe a interface do usuário candidata (ou outra) e para refluir a interface do usuário dos IMEs para evitar desenhar sob o teclado virtual.

Como especificar o layout do teclado virtual preferencial

O IME pode especificar qual layout do teclado virtual usar, e o IME está habilitado a trabalhar com layouts otimizados para touch. Essa funcionalidade é limitada a IMEs para os idiomas de entrada coreano, japonês, chinês simplificado e chinês tradicional.

Há sete layouts com suporte no teclado virtual, três dos quais são layouts clássicos e quatro dos quais são layouts otimizados para touch. Os layouts clássicos têm a mesma aparência e comportamento de um teclado físico.

Todos os três layouts clássicos são para inserir o chinês tradicional em diferentes formas:

• Entrada baseada em fonética
• Entrada Changjie
• Entrada Dayi

Além dos layouts clássicos, há um layout otimizado para touch para cada um dos idiomas de entrada coreano, japonês, chinês simplificado e chinês tradicional.

Para usar essa funcionalidade, o IME deve implementar a interface ITfFnGetPreferredTouchKeyboardLayout, que é exportada pelo IME usando a API ITfFunctionProvider da Estrutura de Serviços de Texto.

Se o IME não oferecer suporte à interface ITfFnGetPreferredTouchKeyboardLayout, o uso do IME resultará no layout clássico padrão para o idioma exibido pelo teclado virtual.

Se o IME precisar definir um dos layouts clássicos como o layout preferencial, nenhum trabalho adicional será necessário no lado do IME além do suporte às interfaces ITfFnGetPreferredTouchKeyboardLayout e ITfFunctionProvider. Porém, é necessário trabalho adicional no IME para trabalhar com os layouts otimizados para touch, e isso é descrito na próxima seção.

Layout otimizado para touch

Os teclados otimizados para touch para os idiomas de entrada coreano, japonês, chinês simplificado e chinês tradicional exibem um layout diferente para os modos de conversão IME Ligado e IME Desligado. Há uma tecla no teclado virtual para definir o modo de conversão do IME como Ligado ou Desligado, mas o modo IME do teclado também pode mudar conforme o foco muda entre os controles de edição.

Os teclados otimizados para touch para os idiomas de entrada japonês, chinês simplificado e chinês tradicional contêm uma tecla ou teclas que o IME usa para navegar pelas páginas candidatas. Para japonês e chinês simplificado, a tecla de página candidata é exibida no layout otimizado para touch. Para o chinês tradicional, há chaves separadas para as páginas anteriores e próximas do candidato.

Quando essas teclas são pressionadas, o teclado virtual chama a função SendInput para enviar os seguintes caracteres da Área de Uso Privado Unicode para o aplicativo com foco, que o IME pode interceptar e no qual pode agir:

• Próxima página (0xF003) – enviada quando a tecla da página candidata é pressionada no teclado otimizado para touch para japonês e chinês simplificado, ou quando a tecla da próxima página é pressionada no teclado otimizado para touch para chinês tradicional.
• Página anterior (0xF004) – enviada quando a tecla da página candidata é pressionada ao mesmo tempo que a tecla Shift no teclado otimizado para touch para japonês e chinês simplificado, ou quando a tecla da página anterior é pressionada no teclado otimizado para touch para chinês tradicional.

Esses caracteres são enviados como entrada Unicode. O próximo parágrafo detalha como extrair as informações de caractere durante as notificações do coletor de eventos de chave que o IME da Estrutura de Serviços de Texto receberá. Esses valores de caractere não são definidos em nenhum arquivo de cabeçalho, portanto, você precisará defini-los em seu código.

Para interceptar a entrada do teclado, o IME deve ser registrado como um coletor de eventos de chave. Para entrada Unicode gerada usando a função SendInput, o parâmetro WPARAM dos retornos de chamada ITfKeyEventSink (OnKeyDown, OnKeyUp, OnTestKeyDown, OnTestKeyUp) sempre contém a chave virtual VK_PACKET e não identifica o caractere diretamente.

Implemente a seguinte sequência de chamadas para acessar o caractere:

// Keyboard state
BYTE abKbdState[256];
if (!GetKeyboardState(abKbdState))
{
   return 0;
}

// Map virtual key to character code
WCHAR wch;
if (ToUnicode(VK_PACKET, 0, abKbdState, &wch, 1, 0) == 1)
{
   return wch;
}

Integração da pesquisa do IME

Dê aos usuários recursos de pesquisa por meio do contrato de pesquisa e da integração com o painel de pesquisa.

Sugestões do painel de pesquisa e do IME

O painel de pesquisa é uma localização central para os usuários realizarem pesquisas em todos os seus aplicativos. Para usuários do IME, o Windows proporciona uma experiência de pesquisa exclusiva que permite que IMEs compatíveis se integrem ao Windows para maior eficiência e usabilidade.

Os usuários que digitam com um IME compatível com a pesquisa obtêm dois benefícios principais:

• Interação perfeita entre o IME e a experiência de pesquisa. Os candidatos do IME são mostrados embutidos na caixa de pesquisa sem ocultar as sugestões de pesquisa. O usuário pode usar o teclado para navegar perfeitamente entre a caixa de pesquisa, os candidatos à conversão do IME e as sugestões de pesquisa.
• Acesso mais rápido a resultados relevantes e sugestões fornecidas pelos aplicativos. O aplicativo tem acesso a todos os candidatos de conversão atuais para dar sugestões mais relevantes. Para priorizar melhor as sugestões de pesquisa, os aplicativos recebem as conversões por ordem de relevância. Os usuários encontram e selecionam o resultado que desejam sem converter, apenas digitando notação fonética.

Um IME será compatível com a experiência de pesquisa integrada se atender aos seguintes critérios:

• Compatível com o shell estilo Windows.
• Implemente as APIs do modo TSF UILess. Para obter mais informações, confira Visão geral do modo UILess.
• Implemente as APIs de integração de pesquisa TSF ITfFnSearchCandidateProvider e ITfIntegratableCandidateListUIElement.

Quando ativado no painel de pesquisa, um IME compatível é colocado no modo sem interface do usuário e não pode mostrar sua interface do usuário. Em vez disso, ele envia candidatos de conversão para o Windows, que os exibe no controle de lista de candidatos embutido, conforme mostra na captura de tela anterior.

Além disso, o IME envia candidatos que devem ser usados para executar a pesquisa atual. Esses candidatos podem ser os mesmos que os candidatos de conversão, ou podem ser adaptados para pesquisa.

Os bons candidatos à pesquisa atendem aos seguintes critérios:

• Sem sobreposição de prefixo. Por exemplo, 北京大学 e北京 são redundantes porque um é um prefixo do outro.
• Sem candidatos redundantes. Candidatos redundantes não são úteis para pesquisa porque não ajudam a filtrar resultados. Por exemplo, qualquer resultado que corresponda a 北京大学 também corresponde a 北京.
• Nenhum candidato de previsão, apenas conversão. Por exemplo, se o usuário digitar "be", o IME poderá retornar 北 como candidato, mas não 北京大学. Normalmente, os candidatos de previsão são muito restritivos.

Os IMEs que não atendem aos critérios não são compatíveis com a exibição de pesquisa da mesma forma que outros controles e não podem usufruir da integração da interface do usuário e os candidatos à pesquisa. Os aplicativos recebem consultas só depois que o usuário terminar de compor.

Quando um aplicativo que oferece suporte ao contrato de pesquisa recebe uma consulta, o evento de consulta contém uma matriz "queryTextAlternatives" com todas as alternativas conhecidas, classificadas da mais relevante (provável) para a menos relevante (improvável).

Quando são fornecidas alternativas, o aplicativo deve tratar cada uma como uma consulta e retornar todos os resultados que correspondem a qualquer uma das alternativas. O aplicativo deve se comportar como se o usuário tivesse emitido várias consultas ao mesmo tempo, essencialmente emitindo uma consulta "ou" ao serviço que fornece os resultados. Para considerações de desempenho, os aplicativos costumam limitar a correspondência entre 5 e 20 das alternativas mais relevantes.

Diretrizes de design da interface do usuário

Todos os IMEs devem seguir as diretrizes de experiência do usuário descritas em Design e código de aplicativos do Windows.

Não use janelas persistentes

Suas janelas do IME devem aparecer apenas quando necessário e não devem ficar visíveis o tempo todo. Quando os usuários não precisam digitar, as janelas do IME não devem ser exibidas. A janela do IME não deve ser uma janela de tela cheia. As janelas do IME não devem se sobrepor. As janelas devem ser projetadas em um estilo do Windows e seguir o dimensionamento da interface do usuário.

Ícones do IME

Existem dois tipos de ícones do IME, ícones de marca e ícones de modo. Todos os ícones do IME devem ser projetados apenas com cores preto e branco. Os novos ícones do IME tomam emprestada a aparência de glifo dos ícones da bandeja do sistema. Esse estilo foi criado para que todas as linguagens possam usá-lo para complementar o visual familiar, ao mesmo tempo em que se diferenciam uns dos outros.

O formato de arquivo para ícones do IME é ICO. Você deve fornecer os seguintes tamanhos de ícone:

• 16x16 pixels
• 20x20 pixels
• 24x24 pixels
• 32x32 pixels
• 40x40 pixels
• 48x48 pixels

Verifique se os ícones de 32 bits com canal alfa são fornecidos em todas as resoluções.

Os ícones da marca IME são definidos por uma caixa branca na qual é colocado um glifo tipográfico renderizado em uma face de tipos moderna. Cada glifo definidor é escolhido pelas respectivas equipes de idiomas. O glifo é preto. A caixa inclui um traço externo de 1 pixel em preto a 50% de opacidade. As versões "novas" são definidas por um canto arredondado no canto superior esquerdo da caixa.

Os ícones do modo IME são definidos por um glifo tipográfico branco em uma face de tipos moderna que inclui um traço externo de 1 pixel em preto a uma opacidade de 50%.

Ícone	Descrição
	Exemplo de ícone de marca IME para ChangeJie chinês tradicional.
	Exemplo de ícone de marca IME para ChangeJie chinês tradicional.
	Exemplo de ícone do modo IME.

Janela própria

Para exibir a interface do usuário candidata, um IME deve definir sua janela como própria, para que possa ser exibida sobre o aplicativo em execução no momento. Use o método ITfContextView::GetWnd para recuperar a janela para a qual possuir. Se GetWnd retornar um erro ou um NULLHWND, chame a função GetFocus.

if (FAILED(pView->GetWnd(&parentWndHandle)) || (parentWndHandle == nullptr)) { parentWndHandle = GetFocus(); }

Interação da janela candidata do IME com superfícies light dismiss.

O modelo de ignorar para janelas pop-up é chamado de "light dismiss" porque é fácil para um usuário fechar essas janelas. Para que os IMEs funcionem bem no modelo de interação do Windows, as janelas do IME devem participar do modelo light dismiss.

Para participar do modelo light dismiss, o IME deve gerar três novos eventos do Windows usando a função NotifyWinEvent ou uma função semelhante. Esses novos eventos são:

• EVENT_OBJECT_IME_SHOW – gerar esse evento quando o IME ficar visível.
• EVENT_OBJECT_IME_HIDE – gerar este evento quando o IME estiver oculto.
• EVENT_OBJECT_IME_CHANGE – gerar esse evento quando o IME se mover ou mudar de tamanho.

Como declarar compatibilidade

Os IMEs declaram que são compatíveis registrando a categoria GUID_TFCAT_TIPCAP_IMMERSIVESUPPORT para seu IME usando ITfCategoryMgr::RegisterCategory.

Definir o modo IME padrão como ativado

Proporcionamos uma experiência do usuário melhor para IMEs.

Suporte a ajuste de DPI para aplicativos da área de trabalho

O suporte avançado a ajuste de DPI permite consultar o nível de reconhecimento de DPI declarado de cada processo da área de trabalho para determinar se ele precisa ajustar a interface do usuário. Em um cenário de vários monitores, o Windows dimensiona a interface do usuário adequadamente para diferentes configurações de DPI em cada monitor.

Como o IME é executado no contexto do processo de cada aplicativo, você não deve declarar um nível de reconhecimento de DPI para o IME. Isso garante que seu IME seja executado no nível de reconhecimento de DPI do processo atual.

Para garantir que todos os elementos da interface do usuário do IME tenham paridade de dimensionamento com os elementos da interface do usuário do processo no qual você está executando, responda adequadamente a valores de DPI diferentes.

Observação

Para garantir a paridade com novos aplicativos da área de trabalho, o IME deve oferecer suporte ao reconhecimento por monitor – DPI, mas não deve declarar um nível de reconhecimento propriamente dito. O sistema determina os requisitos de dimensionamento apropriados em cada cenário.

Para obter detalhes sobre os requisitos de suporte de ajuste de DPI para aplicativos da área de trabalho, consulte DPI alto.

Instalação do IME

Se você criar o IME usando o Microsoft Visual Studio, crie uma experiência de instalação para o IME usando um instalador de terceiros, como o InstallShield da Flexera Software.

As etapas a seguir mostram como usar o InstallShield para criar um projeto de instalação para sua DLL do IME.

• Instalar o Visual Studio.
• Inicie o Visual Studio.
• No menu Arquivo, aponte para Novoe selecione Projeto. A caixa de diálogo Novo projeto é aberta.
• No painel esquerdo, navegue até Modelos > Outros Tipos de Projeto > Configuração e Implantação, clique em Habilitar InstallShield Limited Edition e clique em OK. Siga as instruções de instalação.
• Reinicie o Visual Studio.
• Abrir o arquivo de solução do IME (.sln)
• No Gerenciador de Soluções, clique com o botão direito do mouse na solução, aponte para Adicionar e selecione Novo Projeto. A caixa de diálogo Adicionar novo projeto é aberta.
• No controle de exibição de árvore esquerdo, navegue até Modelos > Outros Tipos de Projeto >InstallShield Limited Edition.
• Na janela central, clique em Projeto do InstallShield Limited Edition.
• Na caixa de texto Nome, digite “SetupIME” e clique em OK.
• Na caixa de diálogo Assistente de Projeto, clique em Informações do aplicativo.
• Preencha o nome da sua empresa e os demais campos.
• Clique em Arquivos de aplicativo.
• No painel esquerdo, clique com o botão direito do mouse na pasta [INSTALLDIR] e selecione Nova pasta. Dê à pasta o nome "Plugins".
• Clique em Adicionar arquivos. Navegue até a DLL do IME e adicione-a à pasta Plugins. Repita esta etapa para o dicionário do IME.
• Clique com o botão direito do mouse no DLL do IME e selecione Propriedades. A caixa de diálogo Propriedades é aberta.
• Na caixa de diálogo Propriedades, clique na guia Configurações de COM & NET.
• Em Tipo de Registro, selecione Autorregistro e clique em OK.
• Compile a solução. A DLL do IME é criada e o InstallShield cria um arquivo .exe instalação que permite aos usuários instalar o IME no Windows.

Para criar sua própria experiência de instalação, chame o método ITfInputProcessorProfileMgr::RegisterProfile para registrar o IME durante a instalação. Não escreva entradas do Registro diretamente.

Se o IME precisar ser utilizável imediatamente após a instalação, chame InstallLayoutOrTip para adicionar o IME aos métodos de entrada habilitados pelo usuário usando o seguinte formato para o parâmetro psz:

<LangID 1>:{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}

Acessibilidade do IME

Implemente a convenção a seguir para fazer com que seus IMEs estejam em conformidade com os requisitos de acessibilidade e para trabalhar com o Narrador. Para tornar as listas de candidatos acessíveis, seus IMEs devem seguir essa convenção.

• A lista de candidatos deve ter um UIA_AutomationIdPropertyId igual a "IME_Candidate_Window" para listas de candidatos de conversão ou "IME_Prediction_Window" para listas de candidatos de previsão.
• Quando a lista de candidatos aparece e desaparece, ela gera eventos dos tipos UIA_MenuOpenedEventId e UIA_MenuClosedEventId, respectivamente
• Quando o candidato selecionado atual muda, a lista de candidatos gera um UIA_SelectionItem_ElementSelectedEventId. O elemento selecionado deve ter uma propriedade UIA_SelectionItemIsSelectedPropertyId igual a TRUE.
• A UIA_NamePropertyId para cada item da lista de candidatos deve ser o nome do candidato. Opcionalmente, você pode fornecer informações adicionais para eliminar a ambiguidade de candidatos por meio de UIA_HelpTextPropertyId.

Tópicos relacionados

• IME
• ITfFnGetPreferredTouchKeyboardLayout
• ITfCompartmentEventSink
• ITfThreadMgrEx::GetActiveFlags
• ITfContextView::GetWnd
• TF_INPUTPROCESSORPROFILE
• ITfFnSearchCandidateProvider
• ITfIntegratableCandidateListUIElement
• SendInput
• Acessibilidade