Exemplo - Editor Java
Introdução
O exemplo do editor Java demonstra as funções padrão disponíveis para os editores de texto personalizados. Também mostra como registar um editor para uma extensão de ficheiro (neste caso .jav) e como definir um fornecedor de documentos personalizados para o editor utilizar. Este exemplo serve apenas como demonstração. O suporte de edição Java é fornecido pelo Eclipse Java Tooling.
O código para este exemplo está no conector org.eclipse.ui.examples.javaeditor
.
Para explorar o código, recomenda-se a importação esse conector para a área de trabalho.
Funções demonstradas no editor de exemplo
-
destaque de sintaxe
-
assistência de conteúdo sensível de tipo de conteúdo (Javadoc e código Java)
-
comunicação entre o delineador e editor de conteúdos, ou seja, a selecção do delineador de conteúdos insere-se no intervalo de realce do editor
-
dois modos de apresentação diferentes
-
marcar o intervalo de realce utilizando um indicador de intervalo visual
-
restringir o editor para mostrar apenas o texto dentro do intervalo de realce (por exemplo, mostrar um método único de uma classe Java)
-
processamento de marcador
-
partilha de documentos
Funções não demonstradas
-
formatação de conteúdos
-
reconciliação dinâmica da página de delineamento de conteúdos
Executar o exemplo do editor Java
-
Criar um projecto
-
Criar um ficheiro com a extensão de ficheiro ".jav" no projecto recém-criado. O exemplo do editor Java abre-se automaticamente.
-
Inserir o código Java. O código Java é colorido de modo dinâmico. O exemplo do editor apresenta os seguintes elementos de linguagem: comentários de linhas múltiplas, comentários de linha única, palavras reservadas à linguagem Java, constantes de cadeia e carácter, código Java normal, bem como comentários de linhas múltiplas que seguem as directrizes de Javadoc. Dentro desses comentários Javadoc, as palavras-chave de Javadoc (verde) e os códigos de HTML (cinzento) estão coloridos de modo diferente.
-
Abrir um novo comentário de linhas múltiplas Java inserindo um "/*" fora de um comentário Java.
Todo o texto entre o "/*" inserido e a primeira ocorrência de "*/" ou o fim do texto muda de cor para vermelho. Anexar outro "*". O vermelho muda de cor para preto, já que o comentário de linhas múltiplas normal é agora tido em consideração como contendo Javadoc. Invocar a assistência de código utilizando CTRL-ESPAÇO.
A função da assistência de conteúdo é suportar o utilizador ao escrever código.
Por isso, ao ser invocada, a assistência de código deverá enumerar todas as conclusões válidas possíveis na localização da invocação. Dentro de Javadoc, o exemplo do editor propõe sempre todas as palavras-chave de Javadoc.
-
Foram de um comentário Java, invocar a sugestão de conteúdo utilizando CTRL+SHIFT+ESPAÇO. São enumeradas cinco propostas. Seleccionar uma proposta e premir a tecla Enter. Aparece uma pequena janela flutuante vermelha por cima da linha actual que mostra a proposta seleccionada.
As sugestões de conteúdo são utilizadas para permitir ao utilizador expressar a intenção (por exemplo, inserir uma chamada de método) e, em seguida, apresentar a informação contextual que guia o utilizador. No exemplo do editor, a proposta é considerada como válida cinco caracteres em redor da localização de invocação inicial. Enquanto a sugestão de conteúdo está visível, invocar a assistência de conteúdo utilizando CTRL+ESPAÇO.
A assistência de conteúdo invocada nesta situação deverá ajudar o utilizador a conseguir atingir a intenção declarada, que continua visível na sugestão de conteúdo. Dentro do código Java normal, o exemplo do editor propõe sempre todas as palavras-chave Java.
-
Guardar o código Java. Guardar actualiza o delineador de conteúdos. O delineador de conteúdos contém dez entradas, cada uma das quais representa um de dez segmentos de tamanho igual do código Java no editor. Este estilo de delineamento de conteúdos foi escolhido para mostrar que a semântica dos intervalos de realce podem ser definidos de modo arbitrário. (Consultar os passos seguintes.)
-
Seleccionar uma das entradas no delineador de conteúdos. As linhas correspondentes estão marcadas com uma barra azul na régua vertical esquerda do editor.
-
Agora, mude para o modo de apresentação segmentada do editor Java. Para isso, certifique-se de que o editor tem a focagem e prima esse botão na barra de ferramentas do escritório, cuja ajuda flutuante diz "Activar/desactivar visualizador de origem segmentado". Esta funcionalidade é utilizada para vistas de método único e funcionalidades semelhantes.
-
Seleccionar uma entrada diferente no delineador de conteúdos. Agora, o editor mostra apenas o segmento seleccionado. Ao anular a selecção da entrada no delineador de conteúdos, o código Java completo é mostrado novamente.
-
Seleccionar uma entrada no delineador de conteúdos, seleccionar uma fracção de texto visível e adicionar uma tarefa para seleccionar. A tarefa aparece na lista de tarefas.
Modificar o código visível. Na lista de tarefas, seleccionar a tarefa criada anteriormente e premir o botão "Ir para ficheiro". A tarefa é seleccionada na área visível, levando em conta, correctamente, as modificações aplicadas anteriormente.
-
Seleccionar outra entrada no delineador de conteúdos. Mostrar a tarefa seleccionada anteriormente na lista de tarefas. O intervalo de realce do editor é aumentado automaticamente para delimitar o intervalo da tarefa revelada.
-
Abrir uma nova área de trabalho. Na nova área de trabalho, abrir um editor Java para o mesmo ficheiro que existe na área de trabalho original. Modificar o conteúdo do editor. Regressar à área de trabalho original. O editor mostra as alterações efectuadas na outra área de trabalho. Os dois editores que mostram os mesmo ficheiros estão ligados.
Princípios para criar editores de texto personalizados
Os passos seguintes são, normalmente, necessários para desenvolver um editor de texto personalizado.
-
Criar um fornecedor de documentos. Um fornecedor de documentos (ver IDocumentProvider) produz e gere documentos (ver IDocument) que contém uma representação textual dos elementos de entrada do editor. É importante decidir como a tradução entre elemento e representação textual deve ser executada, e se o fornecedor de documentos deve ser partilhado ou não entre os editores múltiplos. Ver a classe FileDocumentProvider no exemplo do editor Java.
-
Criar um divisor de partições de documentos. Um divisor de partições de documentos (ver IDocumentPartitioner) divide um documento em regiões não coincidentes. O divisor de partições atribui a cada região um tipo de conteúdo de um conjunto de tipos de conteúdos predefinidos pelo divisor de partições. A cada alteração do documento, a divisão de partições do documento deve ser actualizada. Ver a classe JavaPartitioner no exemplo do editor Java. A classe JavaPartitioner determina as regiões dos tipos "comentários de linhas múltiplas", "comentários Java" e "tudo o resto". Deve assegurar-se que o fornecedor de documentos está definido em cada documento produzido pelo fornecedor de documentos.
-
Determinar qual dos conectores de visualizador de origem que deve ser fornecido. Entre outros conectores suportados estão as estratégias de indentação automática, estratégias de duplo clique, formatador de conteúdos e reconciliador de apresentação de texto. A descrição subsequente será restringida ao reconciliador de apresentação de texto (ver IPresentationReconciler).
No exemplo do editor Java, o reconciliador de apresentação de texto é utilizado para implementar o realce da sintaxe.
-
Criar as extensões apropriadas para todos os conectores de visualizador de origem para cada tipo de conteúdo suportado. Como se vê no caso anterior, o divisor de partições de documentos define os tipos de conteúdos suportados. A implementação predefinida de IPresentationReconciler suporta IPresentationDamagers e IPresentationRepairers como extensões.
Essas extensões são consideradas como específicas de um tipo de conteúdo em particular. Assim sendo, para um editor personalizado, o utilizador deve seleccionar primeiro um sub-conjunto de tipos de conteúdos suportados. As regiões de um tipo no sub-conjunto seleccionado, por exemplo, serão realçadas pela sintaxe. Para cada um desses tipos é necessário implementar as extensões. Ver JavaDamagerRepairer e JavaDocDamagerRepairer no exemplo do editor.
-
Construir uma configuração de visualizador de origem utilizando os conectores e extensões criados anteriormente. Ver JavaSourceViewerConfiguration no exemplo do editor.
-
Personalizar a classe TextEditor ou AbstractTextEditor com o divisor de partições desenvolvido e a configuração de visualizador de origem. Adicionar ou substituir acções e adaptar a construção do menu de contexto do editor. Na versão real, esta personalização pode ser executada num sub-classe. Ver JavaEditor no exemplo do editor.
-
Configurar um colaborador de barra de ferramentas adequado, que efectue a colaboração de acções relacionadas com o editor para a barra de ferramentas e menus do escritório. Ver JavaActionContributor no exemplo do editor.
-
Expandir o ficheiro de configuração XML do conector do editor, de modo a que o editor registe no ponto de extensão do editor predefinido para um conjunto específico de extensões de ficheiros. Além disso, configurar o colaborador de barra de acções no ficheiro XML.
Ver o ficheiro plugin.xml deste exemplo.
Organização de código do exemplo
O código de exemplo do editor Java é organizado em quatro pacotes:
-
org.eclipse.ui.examples.javaeditor
contém todas as classes específicas do editor.
-
org.eclipse.ui.examples.javaeditor.java
contém todos os conectores de visualizador de origem específicos Java como, por exemplo, o JavaDamagerRepairer, bem como o divisor de partições de documentos específico Java.
-
org.eclipse.ui.examples.javaeditor.javadoc
contém todos os conectores de visualizador de origem específicos de Javadoc como, por exemplo, o JavaDamagerRepairer.
org.eclipse.ui.examples.javaeditor.util
contém as classes de conveniência partilhadas pelos outros três pacotes.