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

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 dos 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 –> Tempo & Idioma – Idioma –>> Idiomas preferenciais –> Pacote de idiomas – Opções) para ser o IME padrão para seu idioma preferido.

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

Requisitos de compatibilidade

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

O IME deve ser compatível com aplicativos do Windows

Use o TSF (Text Services Framework) 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 que são 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 para o 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 do Windows afeta os recursos potenciais de um IME.

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

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

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

Não há nenhuma 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 para o modo IME que aparece à esquerda do ícone de marca do IME para que os usuários possam realizar a troca de modo do IME mais comumente usada, 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 idioma em vez do ícone de identidade visual do IME.

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

Ícone do modo IME

Alguns IMEs podem precisar contar com o Indicador de Entrada exibido na bandeja de 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 do modo IME é de 20 x 20 pixels. O ajuste da UI para o ícone do 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 diretórios arquivos de programas ou do Windows. Por padrão, esses diretórios podem ser lidos de um contêiner de aplicativo, para que as mensagens instantâneas 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 as 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 está em execução em um contêiner de aplicativo que tem acesso à Internet, não há nenhuma 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. Alguns IMEs 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.
• Compartilhar 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.

IME e teclado de toque

Seu IME deve garantir que a IU do painel de candidatos e outros elementos de IU não sejam desenhados sob o teclado de toque. 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 do aplicativo em que 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 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 é acionado sempre que o usuário toca em um campo de edição, mesmo que o teclado de toque seja exibido no momento. O IME pode usar essa API para obter o espaço de tela usado pelo teclado na tela antes que o IME desenhe a interface do usuário do candidato (ou outra) e reorganizar a interface do IME para evitar desenhar abaixo do teclado na tela.

Especificando o layout do teclado de toque preferido

O IME pode especificar qual layout de teclado sensível ao toque 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 dos quais 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 em 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 Text Services Framework.

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 um trabalho adicional é necessário 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 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 pelas páginas candidatas. Para japonês e chinês simplificado, a chave de página candidata é exibida no layout com otimização de toque. Para o chinês tradicional, há teclas separadas para as páginas de candidatos anteriores e próximas.

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 japonês e chinês 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 japonês e chinês 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 caracteres durante as notificações de eventos chave que o IME da Text Services Framework 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 receptor de eventos de teclado. 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 do 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, o Windows fornece 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 ao IME são mostrados diretamente na caixa de pesquisa sem bloquear as 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 e sugestões relevantes fornecidos 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 a aplicativos em ordem de relevância. Os usuários encontram e selecionam o resultado desejado sem converter, apenas digitando foneticamente.

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

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

Quando ativado no painel de pesquisa, um IME compatível é colocado no modo sem interface e não pode mostrar sua interface. Em vez disso, ele envia candidatos de conversão para o 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 à pesquisa atendem aos seguintes critérios:

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

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 da interface do usuário e os candidatos à 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) para menos relevantes (improvável).

Quando as 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 que fornece 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 and code Windows apps.

Não use janelas pegajosas

Suas janelas IME só devem aparecer 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. As janelas devem ser projetadas em um estilo do Windows e seguir o dimensionamento da interface do usuário.

Ícones do IME

Há dois tipos de ícones IME: ícones de marca e ícones de modo. Todos os ícones de IME devem ser projetados apenas com cores preto e branco. Os novos ícones de IME inspiram-se na aparência gráfica dos ícones da bandeja do sistema. Esse estilo foi criado para que todos os idiomas possam usá-lo para complementar o visual familiar e, ao mesmo tempo, diferenciar uns dos outros.

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

• 16 x 16 pixels
• 20 x 20 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 o canal alfa são fornecidos em todas as resoluções.

Os ícones da marca IME são definidos por uma caixa branca onde um glifo tipográfico, renderizado em uma tipografia moderna, é colocado. Cada glifo definidor é escolhido por cada equipe de idioma. O glifo é preto. A caixa inclui traço externo de 1 pixel em preto com 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 tipografia moderna que inclui um contorno externo de 1 pixel em preto com 50% de opacidade.

Ícone	Description
	Ícone de marca IME de exemplo para ChangeJie Chinês Tradicional.
	Exemplo de ícone de marca do IME para Cangjie Chinês Tradicional.
	Ícone do modo IME de exemplo.

Janela de propriedade

Para exibir a interface do usuário candidata, um IME deve definir sua janela como uma janela pertencente, para que possa ser exibida sobre o aplicativo em execução no momento. Use o método ITfContextView::GetWnd para recuperar a janela a que deve pertencer. Se a 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 ao IME com superfícies de descarte de luz

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

Para participar do modelo de descarte de luz, seu 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 esse evento quando o IME estiver oculto.
• EVENT_OBJECT_IME_CHANGE – Gerar esse evento quando o IME se 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 uma melhor experiência do usuário 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, o 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 compatibilidade com 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.

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 o 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.

• Instale o 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 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.
• Abra o arquivo de solução 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 à esquerda, navegue até Modelos > Outros Tipos de Projetos > 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 Assistente de Projeto , 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 Settings.
• Em Tipo de Registro, selecione Auto-registro e clique em OK.
• Crie a solução. A DLL IME foi 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 seus IMEs 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 uma 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 é exibida e desaparece, ela gera eventos do tipo UIA_MenuOpenedEventId e UIA_MenuClosedEventId, respectivamente
• Quando o candidato selecionado atual é 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.

Tópicos relacionados

• Editor do Método de Entrada (IME)
• ITfFnGetPreferredTouchKeyboardLayout
• ITfCompartmentEventSink
• ITfThreadMgrEx::GetActiveFlags
• ITfContextView::GetWnd
• TF_INPUTPROCESSORPROFILE
• ITfFnSearchCandidateProvider
• ITfIntegratableCandidateListUIElement
• SendInput
• Acessibilidade