Alterações Requeridas ao Adotar os Mecanismos e APIs do 3.1

Esta seção descreve as alterações que são requeridas, se você estiver tentando alterar o plug-in do 3.0 para adotar os mecanismos e APIs do 3.1.

Suporte ao Comando Desfazer/Refazer da Plataforma

O Eclipse 3.1 fornece uma nova infra-estrutura para definir operações desfeitas e um histórico de operações compartilhado que mantém o controle de operações que foram executadas, desfeitas e refeitas. As várias estruturas desfeitas fornecidas pelos plug-ins de complemento devem ser migradas com o passar do tempo para o suporte de operação de plataforma, para que os clientes dessas estruturas possam integrar-se mais profundamente com a plataforma e disponibilizar suas operações desfeitas para desfazer em outras visualizações e editores de plug-ins. Consulte a documentação Operações Desfeitas para obter informações básicas sobre como incluir o suporte desfeito em um plug-in. Os plug-ins que já definem esse suporte ou utilizam outra estrutura podem ser migrados para o novo suporte desfeito de forma dirigida, conforme descrito a seguir.

Migrando as Classes (Comandos) de Operações Específicas de Plug-in para IUndoableOperation

Os plug-ins que já definem as classes que descrevem suas operações desfeitas devem incluir uma implementação para a interface IUndoableOperation em suas classes de operações/comandos. Eles ainda podem utilizar estruturas mais antigas para gerenciamento do histórico (pilha de comandos) se necessário, mas o fornecimento de uma interface para IUndoableOperation permite aos clientes de um plug-in utilizarem as mesmas operações no histórico de operações de plataforma, mesclar e corresponder operações desfeitas a partir de plug-ins diferentes. Essa estratégia é semelhante àquela utilizada pelos editores de texto do SDK, para migrar para a nova estrutura de operações. Se não for possível um mapeamento direto da interface, os wrappers poderão ser utilizados para mapear o protocolo IUndoableOperation para objetos desfeitos legados. Essa estratégia é utilizada pelo suporte de recriação da Plataforma/JDT. A migração das classes de operações/comandos para IUndoableOperation é uma etapa importante, porque ela permite que as operações desfeitas de estruturas diferentes sejam utilizadas por outros plug-ins sem que cada plug-in tenha que ser completamente migrado.

Migrando Pilhas de Comandos com IOperationHistory

Quando as operações ou comandos desfeitos são expressos em função de IUndoableOperation, os plug-ins que definem um histórico desfeito (pilha de comandos) para manter o controle das operações desfeitas ou refeitas podem migrar para o histórico de operações de plataforma, definindo um IUndoContext que representa o histórico desfeito. Os históricos desfeitos que foram gerenciados anteriormente de forma local podem ser mesclados no histórico de operações comuns, definindo um único contexto desfeito para cada parte ou para cada objeto modelo, incluindo o contexto desfeito apropriado em cada operação e, em seguida, incluindo a operação no histórico de operações de plataforma. Tais históricos com escopo mais global podem ser implementados definindo um único contexto desfeito representando esse escopo do comando, designando esse contexto para cada operação e, em seguida, incluindo a operação no histórico de operações de plataforma. Consulte a documentação Operações Desfeitas para obter os exemplos de criação de contextos desfeitos, designação deles e inclusão de operações no histórico de operações de plataforma.

Definindo Operações Desfeitas Globais no Ambiente de Trabalho

Os plug-ins que querem que suas operações sejam desfeitas das visualizações do ambiente de trabalho, como por exemplo o Navegador ou o Explorador de Pacotes devem designar o contexto desfeito do ambiente de trabalho para suas operações. Consulte a documentação Operações Desfeitas, para obter informações adicionais sobre esse contexto desfeito e como ele pode ser recuperado pelos plug-ins do ambiente de trabalho e do headless.

Rotinas de Tratamento de Ações Desfeitas/Refeitas da Plataforma

Os plug-ins que não definem uma infra-estrutura desfeita ou operações desfeitas, mas que querem fornecer acesso ao histórico desfeito da plataforma, devem considerar o redirecionamento das rotinas de tratamento de ações globais desfeitas e refeitas com as novas rotinas de tratamento de ações comuns desfeitas e refeitas. As rotinas de tratamento de ações devem ser designadas a um contexto desfeito, especificando qual histórico desfeito e refeito deve ser mostrado. Os plug-ins podem utilizar seus contextos desfeitos localmente definidos, para mostrar o histórico desfeito e refeito "local à parte". O contexto desfeito do ambiente de trabalho pode ser utilizado para mostrar o histórico desfeito e refeito amplo do ambiente de trabalho. Novamente, a documentação Operações Desfeitas possui um exemplo completo.

Migrando Ações de Operações de Textos para Rotinas de Tratamento de Ações Comuns

Migrar de ações desfeitas e refeitas do editor de texto é um pouco diferente do que apenas redirecionar as rotinas de tratamento de ações globais desfeitas/refeitas. A estrutura AbstractTextEditor define ações de textos comuns utilizando um TextOperationAction com parâmetro. Essas ações são armazenadas localmente na estrutura e utilizadas para enviar vários comandos para um destino de operação de texto do editor. Para o texto desfeito funcionar corretamente, a estrutura do editor de texto conta com a presença de ações de operações de texto com o ID correto (ITextEditorActionConstants.REDO e ITextEditorActionConstants.UNDO).

AbstractTextEditor foi migrado de forma que as rotinas de tratamento de ações comuns sejam criadas, ainda enquanto as designa para a tabela TextOperationAction com o ID legado. Dessa forma, as novas rotinas de tratamento de ações desfeitas e refeitas possam ser recuperadas, utilizando as técnicas legadas para recuperar a ação e desempenhar uma operação. Os editores de texto na hierarquia AbstractTextEditor herdarão esse comportamento.

Os editores que não herdam esse comportamento de AbstractTextEditor devem considerar a migração de quaisquer ações desfeitas e refeitas existentes, para utilizar as novas rotinas de tratamento. Os editores com TextOperationActions desfeitas e refeitas legadas ainda terão que trabalhar com o suporte desfeito local, desde que a API do gerenciador desfeita do JFace Text utilizada pelas ações ainda sejam suportadas. No entanto, as etiquetas de ações desfeitas e refeitas não serão consistentes com as novas ações desfeitas/refeitas do Eclipse SDK, as quais mostram o nome da operação desfeita ou refeita disponível. Para criar as rotinas de tratamento de ações desfeitas e refeitas comuns, o contexto desfeito utilizado pelo gerenciador desfeito do visualizador de texto deve ser utilizado durante a criação das rotinas de tratamento de ações e tais rotinas devem ser configuradas no editor, utilizando o ID ITextEditorActionConstants apropriado. Consulte AbstractTextEditor.createUndoRedoActions() e AbstractTextEditor.getUndoContext() para obter um exemplo detalhado. Os editores que contam com uma subclasse EditorActionBarContributor para incluir nas barras de ações dos editores, podem utilizar uma técnica semelhante criando as rotinas de tratamento de ações desfeitas e refeitas e configurando-as quando o editor ativo for configurado.

Aprimoramentos de Ajuda

Procura de Informações

Os plug-ins que contribuem com páginas de procura no diálogo Procurar devem considerar a portabilidade de todas as procuras com tipos de informações nos mecanismos de procura federados. Desde a 3.1, todas as procuras de estilo de informações são separadas da procura de artefato do ambiente de trabalho. Os mecanismos de procura de informações são executados em paralelo como tarefas de segundo plano e seus resultados são conferidos na nova visualização Ajuda. Consulte Procura de Ajuda para obter detalhes adicionais.

Ajuda Dinâmica

A nova visualização de ajuda dinâmica funcionará com os IDs de contextos existentes associados estaticamente aos widgets em partes e diálogos do ambiente de trabalho. No entanto, se você mesmo capturar o evento de ajuda e mostrar ajuda, a visualização de ajuda dinâmica não conseguirá mostrar algo útil. Para corrigir o problema, você deve adaptar-se à nova interface IContextProvider como descrito no documento Ajuda do Contexto Dinâmico.

Armazenamentos de Preferências do JFace

A partir do release 3.1, o org.eclipse.jface.preference.IPreferenceStore retornado do AbstractUIPlugin.getPreferenceStore() será uma instância de org.eclipse.ui.preferences.ScopedPreferenceStore. O ScopedPreferenceStore utiliza a API org.eclipse.core.runtime.preferences para gerenciar preferências. No 3.0 ele utilizou a camada de compatibilidade para a interface com uma instância de org.eclipse.core.runtime.Preferences.

No 3.1 removemos a ambigüidade do IPreferenceStore para ser mais específico sobre os tipos dos valores enviados em eventos alterados de preferência. O IPreferenceStore do AbstractUIPlugin#getPreferenceStore tem o mesmo comportamento de antes, mas agora é especificado mais claramente.

Digitando: org.eclipse.jface.util.IPropertyChangeListener incluído em um IPreferenceStore podem ser obtidos dois tipos de valores antigos e novos - representações digitadas ou de Cadeia. Qualquer evento gerado por uma chamada para uma API PreferenceStore digitada (como setValue(String key, boolean value) gerará um evento digitado. Entretanto, também é possível que os eventos sejam propagados das preferências de tempo de execução de núcleo que geram um evento sem tipo (por exemplo, em uma importação de preferência). Listeners de propriedade precisam estar preparados para ambos. Observe também que os eventos digitados não estarão propagando tipos primitivos, portanto, uma chamada para setValue(String key, boolean value) resultará em um evento em que o oldValue e o newValue são Booleanos.

putValue: IPreferenceStore.putValue(String key, String value) não gerará um evento de alteração. Essa API cujo propósito é ser utilizada para preferências privadas, para a qual nenhum listener deseja reagir.

initializeDefaultPreferences. Essa API foi desaprovada no Eclipse 3.0, pois será disparada apenas se a camada de compatibilidade for utilizada. Como a maioria dos plug-ins conta com o AbstractUIPlugin#getPreferenceStore para obter seu armazenamento de preferências, isso estava sendo disparado na inicialização do plug-in anteriormente. Se o plug-in não acessar ele mesmo a camada de compatibilidade, esse método não poderá ser disparado. É recomendável que você crie um org.eclipse.core.runtime.preferences.AbstractPreferenceInitializer para manipular a inicialização de suas preferências.