Exemplo - Ferramenta Readme

Introdução

O editor Readme mostra como definir pontos de extensão para serem utilizados por outros conectores. Também mostra como criar extensões para entradas de menu emergente de recursos, assistentes de novos recursos, editores de ficheiros numa extensão (.readme), uma vista personalizada e páginas de propriedades.

Executar o exemplo

Para começar a utilizar este exemplo, crie um ficheiro com a extensão .readme utilizando o assistente de criação de ficheiros, ou crie um ficheiro utilizando o assistente de criação de exemplos. A vista  adicional fornecida por este exemplo pode ver-se se seleccionar Janela > Mostrar Vista > Outra e se expandir a secção Readme. A acção da vista pode ser vista fazendo clique no ícone Readme na vista Navegador.

Criar um novo ficheiro readme

Criar um novo ficheiro com a extensão .readme.  No menu Ficheiro, seleccionar Novo e depois seleccionar Outro... no sub-menu.  Fazer clique em Simples no assistente, em seguida, seleccionar Ficheiro na lista da esquerda.  Fazer clique em Seguinte para fornecer o nome do ficheiro (certifique-se de que a extensão é .readme) e a pasta no qual deverá estar o ficheiro.

Exemplo de assistentes de criação

No menu Ficheiro, seleccionar Novo e no sub-menu seleccionar Exemplo...  Agora, seleccionar Exemplos de Assistentes de Criação. Seleccionar o ficheiro Readme. Fazer clique em Seguinte. Seleccionar a pasta na qual pretende criar o ficheiro. Inserir o nome do ficheiro com a extensão .readme. Fazer clique em Terminar.

Acção de extensão da vista Readme

Na vista Navegador, seleccionar um ficheiro com a extensão .readme. Se não existir nenhum, crie um ficheiro com essa extensão. Na barra de ferramentas local da vista Navegador, irá ver um botão cuja ajuda flutuante diz "Executar Extensão de Vista Readme".  Fazer clique nesse botão.  Irá aparecer uma caixa de diálogo a dizer "Acção de Vista Executada".

Menus emergentes

Na vista Navegador, seleccionar um ficheiro com a extensão .readme  Se não existir nenhum, crie um ficheiro com essa extensão.  Seleccionar o ficheiro para fazer aparecer o menu emergente.  Repare que existe um artigo do menu que diz "Mostrar Acção Readme" no menu emergente.  Seleccionar esse artigo do menu para abrir uma caixa de diálogo que diga "Acção do Menu Emergente Executada".

Página de preferências

No menu Janela, seleccionar Preferências.  Fazer clique na página chamada Exemplo de Readme.  Isto mostra um exemplo de uma página de preferências.

Página de propriedades

Na vista Navegador, seleccionar um ficheiro com a extensão .readme  Se não existir nenhum, crie um ficheiro com essa extensão.  Seleccionar o ficheiro para fazer aparecer o menu emergente, em seguida, seleccionar o artigo do menu Propriedades.  Fazer clique na página chamada Ferramenta Readme para ver um exemplo de uma página de propriedades.

Editor de ficheiros Readme

O editor de ficheiros Readme é um editor predefinido para ficheiros do tipo *.readme.  Crie um ficheiro com a extensão . readme e abra o ficheiro fazendo duplo clique no mesmo, ou fazendo aparecer o menu emergente,  seleccionando Abrir Com, em seguida, seleccionando Editor de Ficheiros Readme no sub-menu.  Repare que o editor tem um ícone com uma caneta.  Este é o editor que a ferramenta Readme utiliza, por predefinição, para ficheiros do tipo .readme.

Acções do Editor Readme

Demonstra um exemplo de acções que são aplicáveis apenas a um editor específico.  Quando um editor de ficheiros readme tem focagem, repare nos 4 botões da barra de ferramentas adicionais, Executar Extensão de Editor Readme, Acção 1 de Editor Readme, Acção 2 de Editor Readme, Acção 3 de Editor Readme.

Aparece um menu pendente designado como Readme quando um editor de ficheiros readme tem focagem.  Contém as acções descritas anteriormente: Acção 1 de Editor Readme, Acção 2 de Editor Readme, Acção 3 de Editor Readme.

Vista de Secções Readme

Para ver esta vista de Secções Readme, no menu Janela, seleccionar Mostrar Vista, depois seleccionar Outra... no sub-menu.  Expandir o artigo Readme e, em seguida, seleccionar Secções Readme.  Isto irá mostrar uma lista das secções no ficheiro *.readme actual, quando um ficheiro .readme estiver seleccionado na vista Navegador.  Pode também ver a estrutura de um ficheiro *.readme na vista Delinear.

Um ficheiro com extensão .readme pode ser dividido em secções, quando cada secção começar por um número.  Por exemplo, se forem inseridos os textos seguintes no editor de ficheiros readme, a ferramenta readme iria detectar duas secções.  Para ver como as secções são detectadas na ferramenta readme, inserir algum texto no editor de ficheiros readme, guardar o ficheiro, quer premindo CRTL-S ou seleccionando  Ficheiro->Guardar. Abrir a vista Secções Readme e seleccionar o ficheiro .readme na vista Navegador.

Exemplo de texto:

99.1 Esta é a minha primeira secção
Este é um texto na minha primeira secção.

99.1.1 Isto é uma sub-secção
Este é um texto na minha sub-secção.

Arrastar e Largar

A funcionalidade Arrastar e Largar pode ser vista seleccionando uma acção na vista Delinear e arrastando a selecção sobre o topo de um ficheiro de texto. O conteúdo da selecção será anexado ao ficheiro.

Colaboração de ajuda

O exemplo da ferramenta readme demonstra também como utilizar e implementar a ajuda do contexto em todas as extensões que fornece - uma vista, várias acções e uma página do assistente.  Para obter a ajuda de contexto sobre uma acção, colocar o cursor sobre o artigo do menu, mas sem seleccioná-lo, em seguida, premir a tecla F1.  Pode ainda obter ajuda sensível ao contexto (F1) sobre a vista Secções Readme e a página Assistentes de Criação (no assistente Novo).
 

Detalhes

O exemplo da ferramenta Readme declara um ponto de extensão e fornece um número de extensões.  As extensões fornecidas são bastante abrangentes no entendimento de como a Área de trabalho funciona, já que utiliza um número de pontos de extensão mais interessantes declarados pela área de trabalho.  As extensões fornecidas incluídas neste exemplo são vistas e acções de vistas, páginas de preferências, páginas de propriedades, assistentes, editores e acções de editores, menus emergentes, conjuntos de acções, colaborações de ajuda, contextos de ajuda e acções de largar.

Este exemplo fornece também um ponto de extensão declarado no conector. A classe IReadmeFileParser é necessária para qualquer conector que utilize a extensão org.eclipse.ui.examples.readmetool.sectionParser que este exemplo define. A classe DefaultSectionParser é um exemplo da implementação de IReadmeFileParser.

A classe ReadmeEditor implementa IEditorPart e é definida como um editor em ficheiros com a extensão .readme no ficheiro plugin.xml utilizando o ponto de extensão org.eclipse.ui.editors. A classe ReadmeSectionsView implementa IViewPart e é definida como uma vista utilizando o ponto de extensão org.eclipse.ui.views. Este ponto de extensão também define uma categoria para a vista, para utilizar na selecção de vistas.

Neste exemplo são definidos dois tipos de definições de preferências, as preferências da área de trabalho e as preferências dos recursos. As preferências do ambiente de são definidas na classe ReadmePreferencePage que implementa IWorkbenchPreferencePage, de modo a ser adicionado à caixa de diálogo Janela->Preferências. A classe é definida no ponto de extensão org.eclipse.ui.preferencePages no ficheiro plugin.xml. As duas páginas de propriedades dos recursos são ReadmeFilePropertyPage e ReadmeFilePropertyPage2, ambas implementam IWorkbenchPropertyPage. Ambas são definidas a invocar no tipo IFile pelo código objectClass no ficheiro plugin.xml no ponto de extensão org.eclipse.ui.propertyPages.

A classe ReadmeCreationWizard implementa INewWizard e é definida no ponto de extensão org.eclipse.ui.newWizards no ficheiro plugin.xml. Este ponto de extensão também define a categoria do assistente que é mostrado quando o utilizador seleccionar Ficheiro->Novo->Exemplo...

São adicionadas várias rotinas fictícias de acção a este exemplo. O conjunto de acções declara um menu identificado como Editor de Ficheiros Readme a incluir na barra do menu da janela da área de trabalho, utilizando o ponto de extensão org.eclipse.ui.actionSets. Define também uma acção para a barra de ferramentas e para a barra do menu da área de trabalho, utilizando os códigos toolbarPath e menubarPath. Utilizar a classe WindowActionDelegate que implementa IWorkbenchWindowActionDelegate para implementar a acção. A acção para o menu emergente é definida como uma objectContribution pela classe PopupMenuActionDelegate no  ponto de extensão org.eclipse.ui.popupMenus. PopupMenuActionDelegate implementa IObjectActionDelegate e utiliza o IWorkbenchPart fornecido para abrir uma caixa de diálogo de mensagem. A acção de vista ViewActionDelegate é definida no ponto de extensão org.eclipse.ui.viewActions e implementa IViewActionDelegate. A vista em que aparece é definida pelo código targetID, que neste exemplo é org.eclipse.ui.views.ResourceNavigator. A acção do editor é definida pela classe EditorActionDelegate que implementa IEditorActionDelegate e é adicionada utilizando o ponto de extensão org.eclipse.ui.editorActions. O editor ao qual é aplicado é definido pelo código targetID, que neste exemplo é definido em org.eclipse.ui.examples.readmetool.ReadmeEditor.

A classe ReadmeDropActionDelegate implementa IDropDelegate. Os IDropDelegates são informados sempre que é executada uma acção largar na área de trabalho. O ponto de extensão para esta acção é org.eclipse.ui.dropActions.