Composições

Uma composição é um estado de entrada temporário que permite que um serviço de texto especifique ao aplicativo e ao usuário que o texto de entrada ainda está em um estado de alteração. Um aplicativo pode e deve obter informações de atributo de exibição sobre a composição e usar essas informações para exibir o estado da composição para o usuário.

Um exemplo do uso de uma composição é durante a entrada da fala. Enquanto o usuário está falando, o serviço de texto de fala cria uma composição. Esta composição permanecerá intacta até que toda a entrada de fala esteja completa. Quando a sessão termina, o serviço de texto de fala encerra a composição.

Um aplicativo usa a presença e ausência de uma composição para determinar como exibir texto e o que, se houver, processamento deve ser realizado no texto. Por exemplo, se o usuário estiver usando o mecanismo de fala para inserir texto, o aplicativo não deve executar nenhuma verificação ortográfica ou gramatical em qualquer texto de composição. O texto é considerado incompleto até que a composição seja encerrada.

Serviços de Texto

Um serviço de texto cria uma composição chamando ITfContextComposition::StartComposition. O serviço de texto pode, opcionalmente, implementar um ITfCompositionSink objeto que recebe notificações de eventos de composição. StartComposition retorna um ITfComposition objeto que o serviço de texto mantém uma referência e usa para modificar e encerrar a composição. O serviço de texto encerra a composição chamando ITfComposition::EndComposition.

Se um serviço de texto vai criar composições, ele também deve oferecer suporte a atributos de exibição para permitir que um aplicativo exiba texto que faz parte de uma composição de forma diferente do texto padrão. Para obter mais informações, consulte Fornecendo atributos de exibição.

Aplicações

Um aplicativo pode monitorar a criação, alteração e término de composições instalando um ITfContextOwnerCompositionSink coletor. Quando uma composição é iniciada, ITfContextOwnerCompositionSink::OnStartComposition é chamado. Da mesma forma, quando uma composição é alterada ou encerrada, ITfContextOwnerCompositionSink::OnUpdateComposition e ITfContextOwnerCompositionSink::OnEndComposition serão chamados, respectivamente.

A seguir está um procedimento típico para atualizar um documento usando uma composição.

1. ITextStoreACP::InsertTextAtSelection ou ITextStoreAnchor::InsertTextAtSelection são normalmente usados para inserir o texto inicial na composição.
2. A composição é iniciada com uma chamada para ITfContextComposition::StartComposition, usando o intervalo de texto retornado por InsertTextAtSelection.
3. Quando recebe novas entradas, como entrada de voz ou teclado, o aplicativo atualiza a composição com ITextStoreACP::SetText ou ITextStoreAnchor::SetText.
4. Quando o aplicativo determina que é hora de terminar a composição, ele chama ITfComposition::EndComposition.

O aplicativo deve usar os atributos de exibição fornecidos pelo serviço de texto para modificar a exibição de texto em todos os momentos e não apenas quando uma composição está ativa. Para obter mais informações, consulte Usando atributos de exibição.

Se necessário, um aplicativo pode encerrar uma composição chamando ITfContextOwnerCompositionServices::TerminateComposition.