Exemplo - Ferramenta Leia-me

Introdução

O editor Leia-me mostra como definir seus próprios pontos de extensão para usar outros plug-ins. Também mostra como criar extensões para entradas de menu pop-up de recurso, novos assistentes de recursos, editores de arquivos para uma extensão (.readme), uma exibição personalizada e páginas de propriedade.

Executando o exemplo

Para começar a usar esse exemplo, crie um arquivos com extensão .readme usando um assistente de criação de arquivo ou crie um usando o assistente de criação de exemplo. A exibição adicional  fornecida por este exemplo pode ser vista selecionando Janela > Mostrar Visualização > Outro e expandindo a seção LEIA-ME. A ação da exibição pode ser vista clicando-se no ícone leia me na Visualização Navegador.

Criando um novo arquivo leia-me

Crie um novo arquivo com a extensão .readme.  No menu Arquivo, selecione Novo e, em seguida, selecione Outro... no submenu.  Clique em Simples no assistente e, em seguida, selecione Arquivo na lista à esquerda.  Clique em Avançar para fornecer o nome do arquivo (certifique-se de que a extensão seja .readme) e a pasta na qual o arquivo deverá ficar.

Exemplo de assistentes de criação

No menu Arquivo, selecione Novo e no submenu selecione Exemplo...  Agora selecione Assistentes de Criação de Exemplo. Selecione o Arquivo Readme. Clique em Avançar. Selecione a pasta em que o arquivo será criado. Digite o nome do arquivo com extensão .readme. Clique em Concluir.

Ação de extensão de exibição leia me

Na exibição Navegador, selecione um arquivo com extensão .readme. Se não houver, crie um com essa extensão. Na barra de ferramentas local da Visualização Navegador, você verá um botão cuja ajuda instantânea diz Executar Extensão de Visualização do LEIA-ME.  Clique nesse botão.  Um diálogo pop-up informará que a Ação de Visualização foi executada.

Menus Pop-up

Na Visualização do Navegador, selecione um arquivo com a extensão .readme.  Se não houver nenhum, crie um arquivo com essa extensão.  Selecione o arquivo para tornar visível o menu pop-up.  Observe que há um item no menu pop-up que diz Mostrar Ação do LEIA-ME.  Escolha esse item de menu para abrir um diálogo que diz Ação do Menu Pop-up Executada.

Página de Preferência

No menu Janela, selecione Preferências.  Clique na página chamada Exemplo do LEIA-ME.  Isso mostrará o exemplo de uma página de preferência.

Página de Propriedade

Na Visualização Navegador, selecione um arquivo com a extensão .readme.  Se não houver nenhum, crie um arquivo com essa extensão.  Selecione o arquivo para tornar visível o menu pop-up e, em seguida, selecione o item de menu Propriedades.  Clique na página chamada Ferramenta LEIA-ME para ver o exemplo de uma página de propriedade.

Editor de Arquivo LEIA-ME

O Editor de Arquivo LEIA-ME é o editor padrão para os arquivos do tipo *.readme.  Crie um arquivo com a extensão .readme e abra-o com um clique duplo ou tornando o menu pop-up visível,  selecionando Abrir com e, em seguida, selecionando Editor de Arquivo LEIA-ME no submenu.   Observe que o editor possui um ícone com um lápis.  Esse é o editor que a ferramenta LEIA-ME utiliza por padrão para arquivos do tipo *.readme.

Ações do Editor LEIA-ME

Isso demonstra um exemplo de ações aplicáveis somente a um editor em particular.  Quando um editor de arquivo LEIA-ME estiver em foco, observe 4 botões adicionais na barra de ferramentas - Executar Extensão do Editor LEIA-ME, Ação 1 do Editor LEIA-ME, Ação 2 do Editor LEIA-ME, Ação 3 do Editor LEIA-ME.

Um menu pull down chamado LEIA-ME é mostrado quando um editor de arquivo LEIA-ME está em foco.  Ele contém as ações anteriormente descritas: Ação 1 do Editor LEIA-ME, Ação 2 do Editor LEIA-ME, Ação 3 do Editor LEIA-ME.

Visualização das Seções LEIA-ME

Para ver essa exibição Seções LEIA-ME, no menu Janela, selecione Mostrar Visualização e, em seguida, selecione Outro... no submenu.  Expanda o item LEIA-ME e, em seguida, selecione Seções LEIA-ME.  Isso mostrará uma lista das seções no arquivo *.readme atual, quando um arquivo .readme for selecionado na Visualização do Navegador.  Você também poderá ver a estrutura de um arquivo *.readme na exibição Outline.

Um arquivo com a extensão .readme pode ser dividido em seções quando cada seção começa com um número.  Por exemplo, se o texto seguinte fosse digitado no editor de arquivo LEIA-ME, a ferramenta LEIA-ME detectaria 2 seções.  Para ver como as seções são detectadas na ferramenta LEIA-ME, digite um texto no editor de arquivo LEIA-ME, salve o arquivo pressionando CTRL-S ou selecionando  Arquivo->Salvar. Abra a exibição Seções LEIA-ME e selecione o arquivo .readme na exibição Navegador.

Texto de Exemplo:

99.1 Essa é minha primeira seção.
Existe algum texto na minha primeira seção.

99.1.1 Essa é uma subseção
Há algum texto na minha subseção.

Arrastar e Soltar

A funcionalidade arrastar e soltar pode ser vista selecionando a seção na Visualização Esboço e arrastando a seleção para cima a parte superior do arquivo de texto. O conteúdo da da seleção será anexado ao arquivo.

Contribuição da Ajuda

O exemplo da ferramenta LEIA-ME também demonstra como utilizar e implementar a ajuda de contexto em todas as extensões fornecidas - uma exibição, várias ações e uma página de assistente.   Para obter a ajuda de contexto em uma ação, focalize o item de menu, mas não o selecione; em seguida, pressione a tecla F1.  Você também pode obter a ajuda sensível ao contexto (F1) na exibição Seções LEIA-ME e na página Assistentes de Criação de Exemplos (no assistente Novo).
 

Detalhes

O exemplo da Ferramenta LEIA-ME declara um só ponto de extensão e fornece várias extensões.  As extensões fornecidas são bastante abrangentes na compreensão de como o Workbench funciona, na medida em que utiliza vários dos mais interessantes pontos de extensão declarados Workbench.   As extensões fornecidas, incluídas neste exemplo, são exibições e ações de exibição, páginas de preferências, páginas de propriedade, assistentes, editores e ações de editores, menus pop-up, conjuntos de ações, contribuições de ajuda, contextos de ajuda e ações eliminar.

Esses exemplos também fornecer um ponto de extensão declarado no plug-in. A classe IReadmeFileParser é necessário para qualquer plug-in que use a extensão org.eclipse.ui.examples.readmetool.sectionParser definida no exemplo. A classe DefaultSectionParser é uma implementação do exemplo de IReadmeFileParser.

A classe ReadmeEditor implementa o IEditorPart e é definida como um editor de arquivos com extensão .readme no plugin.xml usando o ponto de extensão org.eclipse.ui.editors. A classe ReadmeSectionsView implementa o IViewPart e é definida como uma exibição usando o ponto de extensão org.eclipse.ui.views. Esse ponto de extensão também define a categoria para a exibição a ser usada na seleção da exibição.

Dois tipos de configurações de referência são definidos nesse exemplo: preferências do workbench e propriedades de recursos. A preferência do workbench é definida na classe ReadmePreferencePage, que implementa a IWorkbenchPreferencePage de forma que ela seja adicionada ao diálogo Janela->Preferências. A classe é definida no ponto de extensão org.eclipse.ui.preferencePages em plugin.xml. As duas páginas de propriedades de recursos são ReadmeFilePropertyPage e ReadmeFilePropertyPage2 e ambas implementam IWorkbenchPropertyPage. Eles estão definidos para serem chamados no tipo IFile pela marcação objectClass em 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 em plugin.xml. Esse ponto de extensão também define a categoria em que o assistente é mostrado quando o usuário seleciona Arquivo->Novo->Exemplo....

Muitos stubs de ações são incluídos nesse exemplo. O conjunto de ações declara que o menu chamado Editor de Arquivo Leia-me para ser incluído na barra de menus da janela do workbench usando o ponto de extensão org.eclipse.ui.actionSets. Ele também define uma ação para a barra de ferramenta e para a barra de menus usando as marcações toolbarPath menubarPath. Ele usa a classe WindowActionDelegate que implemente IWorkbenchWindowActionDelegate para implementar a ação. A ação para o menu pop-up é definida com um objectContribution pela classe PopupMenuActionDelegate no  ponto de extensão org.eclipse.ui.popupMenus. PopupMenuActionDelegate implementa IObjectActionDelegate e usa o IWorkbenchPart fornecido para abrir o diálogo de mensagem. A ação da exibição ViewActionDelegate é definida no ponto de extensão org.eclipse.ui.viewActions e implementa IViewActionDelegate. A Visualização que aparece é definida pela marcação de ID de destino o que nesse exemplo é org.eclipse.ui.views.ResourceNavigator. A ações do editor é definida pela classe EditorActionDelegate que implementa IEditorActionDelegate e é incluída usando o ponto de extensão org.eclipse.ui.editorActions. O editor aplicado é definido pela marcação de ID de destino que nesse exemplo é definido em org.eclipse.ui.examples.readmetool.ReadmeEditor.

A classe ReadmeDropActionDelegate implementa IDropDelegate. IDropDelegates são informadas cada vez que há uma ação de soltar no workbench . O ponto de extensão para essa ação é org.eclipse.ui.dropActions.