Requisitos do IME (Editor de Método de Entrada Personalizado)

Artigo
04/16/2022
19 minutos para ler

Essas diretrizes e requisitos podem ajudá-lo a desenvolver um IME (Editor de Método de Entrada) personalizado para ajudar um texto de entrada do usuário em um idioma que não pode ser representado facilmente em um teclado QWERTY padrão.

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

IME padrão

Um usuário pode selecionar qualquer um de seus IMEs ativos (Configurações -> Idioma do Tempo & - Idioma -> Idiomas> preferenciais -> Pacote de idiomas - Opções) para ser o IME padrão para seu idioma preferido.

Preferred language setting

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

Preferred language keyboard

Importante

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

Requisitos de compatibilidade

Veja a seguir os requisitos básicos de compatibilidade para um IME personalizado.

O IME deve ser compatível com aplicativos Windows

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

Quando um aplicativo é iniciado, o TSF carrega a DLL IME para o IME que está selecionado no momento pelo usuário. 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 que as versões anteriores do Windows, mas ser carregado em um aplicativo Windows afeta os recursos potenciais de um IME.

Se o IME precisar fornecer diferentes funcionalidades ou interface do usuário entre aplicativos 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 em seu IME e verifique o sinalizador TF_TMF_IMMERSIVEMODE, para que seu IME dispare uma lógica de aplicativo diferente dependendo do resultado.

Windows aplicativos não dão suporte a IMEs do TTS (Serviço de Texto de Tabela).

Observação

Algumas ferramentas para gerar IMEs TTS produzem IMEs marcadas como malware por Windows.

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

Não há nenhuma barra de idiomas para hospedar ícones de 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 mostra à esquerda do ícone de identidade visual do IME para que os usuários executem o comutador de modo IME mais usado, como ativar ou desativar o IME.

O Indicador de Entrada mostra o ícone de identidade visual do IME e o ícone de modo somente para IMEs compatíveis. 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 de linguagem em vez do ícone de identidade visual do IME.

Armazene os ícones de IME em um arquivo DLL ou EXE, em vez de um arquivo .ico autônomo. O design de ícones de 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 IME da DLL IME usando a ID do recurso definida pelo IME quando ela foi registrada no sistema.

Ícone do modo IME

Alguns IMEs podem precisar contar com o 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 16 x 16 pixels. O dimensionamento da interface do usuário segue a 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 Segura), o tamanho padrão do ícone de modo IME é de 20 x 20 pixels. O ícone de dimensionamento da interface do usuário para o modo IME no UAC segue o PPI.

O IME deve funcionar no contêiner do aplicativo

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

Arquivos de Dicionário – Com frequência, os IMEs têm arquivos de dicionário somente leitura para mapear a entrada do usuário para caracteres específicos. Para acessar esses arquivos de dentro de um contêiner de aplicativo, seu IME deve colocá-los nos arquivos de programas ou Windows diretórios. Por padrão, esses diretórios podem ser lidos de um contêiner de aplicativo, para que as IMEs possam 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 a ACL (Listas de Controle de Acesso) dos arquivos de dicionário para permitir o acesso de contêineres de aplicativo.
Atualização da Internet - Se o IME precisar atualizar seus dicionários usando dados da Internet, ele não poderá fazer isso de forma confiável dentro de um contêiner de aplicativo, pois o acesso à Internet nem sempre é permitido. Em vez disso, seu IME deve executar um processo de área de trabalho separado responsável por atualizar os arquivos de dicionário com dados da Internet.
Aprendizado on-the-fly - Se um IME estiver em execução em um contêiner de aplicativo que tenha acesso à Internet, não haverá restrição nos pontos de extremidade com os quais o IME pode se comunicar. Nesse caso, um IME pode usar um servidor de nuvem para fornecer serviços de aprendizagem on-the-fly. Algumas mensagens instantâneas baixam e carregam a entrada do 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 pode nem sempre 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 aplicativo diferentes. Use um serviço Web para compartilhar dados entre aplicativos.

Importante

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

IME e teclado virtual

Seu 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 banda de ordem z maior do que todos os aplicativos e a interface do usuário do IME é exibida na mesma banda de ordem z em que o aplicativo está ativo. Como resultado, 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 contabilizar 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 and Hide do teclado virtual. O evento Show é acionado sempre que o usuário toca em um campo de edição, mesmo que o teclado virtual seja exibido no momento. Seu IME pode usar essa API para obter o espaço de tela usado pelo teclado virtual antes que o IME desenhe o candidato (ou outra) interface do usuário e refluxe a interface do usuário de IMEs para evitar desenhar abaixo do teclado virtual.

Especificando o layout de teclado virtual preferencial

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

Há sete layouts compatíveis com o teclado virtual, três dos quais são layouts clássicos e quatro são layouts com otimização de toque. Os layouts clássicos parecem e se comportam como um teclado físico.

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

Entrada baseada em fonética
Entrada changjie
Entrada dayi

Além dos layouts clássicos, há um layout com otimização de toque para cada um dos idiomas de entrada coreano, japonês, chinês simplificado e chinês tradicional.

Para usar essa funcionalidade, seu 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 der 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 de dar suporte às interfaces ITfFnGetPreferredTouchKeyboardLayout e ITfFunctionProvider. Mas é necessário trabalho adicional no IME para trabalhar com os layouts com otimização de toque, e isso é descrito na próxima seção.

Layout com otimização de toque

Os teclados com otimização de toque 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 On e IME Off. Há uma tecla no teclado virtual para definir o modo de conversão de IME como Ativado ou Desativado, mas o modo IME do teclado também pode mudar conforme o foco muda entre os controles de edição.

Os teclados com otimização de toque para os idiomas de entrada japonês, chinês simplificado e chinês tradicional contêm uma chave ou teclas, que o IME usa para navegar por páginas candidatas. Para chinês japonês e simplificado, a chave de página do candidato é exibida no layout com otimização de toque. Para chineses tradicionais, há chaves separadas para as páginas anteriores e próximas candidatas.

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 focado, no qual o IME pode interceptar e agir:

Próxima página (0xF003) - Enviada quando a tecla de página candidata é pressionada no teclado com otimização de toque para chinês japonês e simplificado, ou quando a tecla da próxima página é pressionada no teclado com otimização de toque para chinês tradicional.
Página anterior (0xF004) - Enviada quando a tecla de página candidata é pressionada ao mesmo tempo que a tecla Shift no teclado com otimização de toque para chinês japonês e simplificado ou quando a tecla de página anterior é pressionada no teclado com otimização de toque 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 principais notificações do coletor de eventos 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, seu IME deve se registrar 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 de pesquisa de IME

Forneça aos usuários recursos de pesquisa por meio do contrato de pesquisa e integração com o painel de pesquisa.

Painel de pesquisa e sugestões de IME

O painel de pesquisa é um local central para os usuários executarem pesquisas em todos os seus aplicativos. Para usuários de IME, Windows fornece uma experiência de pesquisa exclusiva que permite a integração de IMEs compatíveis com 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 ocluir sugestões de pesquisa. O usuário pode usar o teclado para navegar diretamente entre a caixa de pesquisa, os candidatos à conversão de IME e as sugestões de pesquisa.
Acesso mais rápido a resultados relevantes e sugestões fornecidas por aplicativos. O aplicativo tem acesso a todos os candidatos de conversão atuais para fornecer sugestões mais relevantes. Para priorizar melhor as sugestões de pesquisa, as conversões são dadas aos aplicativos em ordem de relevância. Os usuários encontram e selecionam o resultado desejado sem converter, apenas digitando fonético.

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

Compatível com o shell de estilo Windows.
Implemente as APIs de modo UILess do TSF. Para obter mais informações, consulte a visão geral do modo sem interface do usuário.
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 Windows, que os exibe no controle de lista de candidatos embutidos, conforme mostrado 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 iguais aos candidatos de conversão, ou podem ser adaptados para pesquisa.

Bons candidatos de 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. Qualquer candidato redundante não é útil para pesquisa porque não ajuda a filtrar resultados. Por exemplo, qualquer resultado que corresponda a 北京大学 também corresponde a 北京.
Nenhum candidato de previsão, somente conversão. Por exemplo, se o usuário digitar "ser", o IME poderá retornar 北 como um candidato, mas não 北京大学. Normalmente, os candidatos à 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 aproveitar a integração de interface do usuário e os candidatos de pesquisa. Os aplicativos recebem consultas somente depois que o usuário terminar de redigir.

Quando um aplicativo que dá suporte ao contrato de pesquisa recebe uma consulta, o evento de consulta contém uma matriz "queryTextAlternatives" que contém todas as alternativas conhecidas, classificadas das mais relevantes (provavelmente) como menos relevantes (improvável).

Quando alternativas são fornecidas, o aplicativo deve tratar cada alternativa como uma consulta e retornar todos os resultados que correspondam 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" para o serviço fornecendo os resultados. Para considerações de desempenho, os aplicativos geralmente limitam 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 Windows aplicativos.

Não use janelas pegajosas

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

Ícones de IME

Há dois tipos de ícones de IME, ícones de identidade visual e ícones de modo. Todos os ícones de IME devem ser projetados apenas com cores em preto e branco. Os novos ícones de IME são emprestados da aparência glifo dos ícones da bandeja do sistema. Esse estilo foi criado para que todos os idiomas possam usá-lo para complementar o visual familiar, além de diferenciar uns dos outros.

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

16 x 16 pixels
20x20 pixels
24 x 24 pixels
32 x 32 pixels
40 x 40 pixels
48 x 48 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 um glifo tipográfico renderizado em uma face de tipo moderna é colocado. Cada glifo definidor é escolhido por cada equipe de idioma. 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 tipo moderna que inclui um traço externo de 1 pixel em preto a 50% de opacidade.

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

Janela de propriedade

Para exibir a interface do usuário do candidato, um IME deve definir sua janela como de propriedade, para que possa ser exibida pelo 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 do candidato do IME com superfícies de descarte de luz

O modelo de demissão 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 Windows, as janelas IME devem participar do modelo de descarte de luz.

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

EVENT_OBJECT_IME_SHOW - Gere esse evento quando o IME ficar visível.
EVENT_OBJECT_IME_HIDE - Acione esse evento quando o IME estiver oculto.
EVENT_OBJECT_IME_CHANGE - Aumente esse evento quando o IME mover ou alterar o tamanho.

Declarando 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

Fornecemos um UX melhor para IMEs.

Suporte ao dimensionamento de DPI para aplicativos da área de trabalho

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

Como seu IME é executado no contexto do processo de cada aplicativo, você não deve declarar um nível de reconhecimento de DPI para seu 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 em que você está executando, você deve responder adequadamente a diferentes valores de DPI.

Observação

Para garantir a paridade com novos aplicativos de área de trabalho, seu IME deve dar suporte por reconhecimento de monitor-DPI, mas não deve declarar um nível de conscientização em si. O sistema determina os requisitos de dimensionamento apropriados em cada cenário.

Para obter detalhes sobre os requisitos de suporte ao dimensionamento de DPI para aplicativos da Área de Trabalho, consulte Alta DPI.

Instalação do IME

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

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

Instalar Visual Studio.
Inicie o Visual Studio.
No menu Arquivo, aponte para Novo e selecione Project. A caixa de diálogo Novo projeto é aberta.
No painel esquerdo, navegue até Modelos > Outros Project Configuração e Implantação de Tipos>, clique em Habilitar InstallShield Limited Edition e clique em OK. Siga as instruções de instalação.
Reinicie o Visual Studio.
Abra o arquivo de solução IME (.sln).
Em Gerenciador de Soluções, clique com o botão direito do mouse na solução, aponte para Adicionar e selecione Nova Project. A caixa de diálogo Adicionar Novo Project é aberta.
No controle de exibição de árvore à esquerda, navegue até Modelos > Outros tipos > de Project InstallShield Limited Edition.
Na janela central, clique em InstallShield Limited Edition Project.
Na caixa de texto Nome , digite "SetupIME" e clique em OK.
Na caixa de diálogo Project Assistente, clique em Informações do Aplicativo.
Preencha o nome da empresa e os outros campos.
Clique em Arquivos de Aplicativo.
No painel esquerdo, clique com o botão direito do mouse na pasta [INSTALLDIR] e selecione Nova Pasta. Nomeie a pasta "Plug-ins".
Clique em Adicionar Arquivos. Navegue até a DLL do IME e adicione-a à pasta Plug-ins . Repita esta etapa para o dicionário IME.
Clique com o botão direito do mouse na DLL do IME e selecione Propriedades. A caixa de diálogo Propriedades é aberta.
Na caixa de diálogo Propriedades, clique na guia com & .NET Configurações.
Em Tipo de Registro, selecione Auto-registro e clique em OK.
Compile a solução. A DLL IME é criada e o InstallShield cria um arquivo setup.exe que permite que os usuários instalem seu 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 para o 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 suas mensagens instantâneas estejam em conformidade com os requisitos de acessibilidade e trabalhem com o Narrador. Para tornar as listas de candidatos acessíveis, suas mensagens instantâneas devem seguir esta 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 à previsão.
Quando a lista de candidatos aparece e desaparece, ela gera eventos do tipo UIA_MenuOpenedEventId e UIA_MenuClosedEventId, respectivamente
Quando o candidato atual selecionado é alterado, a lista de candidatos gera um UIA_SelectionItem_ElementSelectedEventId. O elemento selecionado deve ter uma propriedade UIA_SelectionItemIsSelectedPropertyId igual a TRUE.
O UIA_NamePropertyId para cada item na lista de candidatos deve ser o nome do candidato. Opcionalmente, você pode fornecer informações adicionais para desambiguar candidatos por meio de UIA_HelpTextPropertyId.