Ejemplo - Herramienta Readme

Introducción

El editor Readme muestra cómo definir sus propios puntos de extensión para su uso por parte de otros conectores. También muestra cómo crear extensiones para entradas de menús emergentes de recursos, asistentes de nuevos recursos, editores de archivos en una extensión (.readme), una vista personalizada y páginas de propiedades.

Ejecución del ejemplo

Para empezar a utilizar este ejemplo, cree un archivo con la extensión .readme mediante el asistente de creación de archivos, o cree uno mediante el asistente de creación de ejemplos. La vista adicional  proporcionada por este ejemplo puede verse seleccionando Ventana > Mostrar vista > Otras y expandiendo la sección Readme. La acción de vista puede verse pulsando sobre el icono de readme en la vista Navegador.

Creación de un archivo readme nuevo

Cree un archivo nuevo con la extensión de archivo .readme.  En el menú Archivo, seleccione Nuevo y, a continuación, Otros... en el submenú.  Pulse en Simple en el asistente y, a continuación, seleccione Archivo en la lista de la izquierda.  Pulse en Siguiente para proporcionar el nombre de archivo (asegúrese de que la extensión sea .readme) y la carpeta que debe contener el archivo.

Asistentes de creación de ejemplos

En el menú Archivo, seleccione Nuevo y, en el submenú, seleccione Ejemplo...  A continuación seleccione Asistentes de creación de ejemplos. Seleccione Archivo Readme. Pulse Siguiente. Seleccione la carpeta en la que desea que se cree el archivo. Escriba el nombre del archivo con la extensión .readme. Pulse Finalizar.

Acción de extensión de vista Readme

En la vista Navegador, seleccione un archivo con la extensión .readme. Si no hay ninguno, cree un archivo con esa extensión. En la barra de herramientas local de la vista Navegador, verá un botón cuya ayuda flotante dice Ejecutar extensión de vista Readme.  Pulse en este botón.  Aparecerá un diálogo que indica Acción de ver ejecutada.

Menús emergentes

En la vista Navegador, seleccione un archivo con la extensión .readme.  Si no hay ninguno, cree un archivo con esa extensión.  Seleccione el archivo para mostrar el menú emergente.  Tenga en cuenta que hay un elemento de menú que dice Mostrar acción de readme en el menú emergente.  Seleccione este elemento de menú para abrir un diálogo que indica Acción de menú emergente ejecutada.

Página de Preferencias

En el menú Ventana, seleccione Preferencias.  Pulse en la página denominada Ejemplo de readme.  Muestra un ejemplo de una página de preferencias.

Página de propiedades

En la vista Navegador, seleccione un archivo con la extensión .readme.  Si no hay ninguno, cree un archivo con esa extensión.  Seleccione el archivo para mostrar el menú emergente y, a continuación, seleccione el elemento de menú Propiedades.  Pulse en la página denominada Herramienta Readme para ver un ejemplo de página de propiedades.

Editor de archivos readme

El Editor de archivos readme es el editor emergente para los archivos de tipo *.readme.  Cree un archivo con la extensión .readme y ábralo efectuando una doble pulsación en el mismo, o bien muestre el menú emergente,  seleccione Abrir con y, a continuación, seleccione Editor de archivos readme en el submenú.  Observe que el editor tiene un icono con un lápiz.  Es el editor que la herramienta Readme utiliza por omisión para los archivos de tipo *.readme.

Acciones del editor Readme

Muestra un ejemplo de las acciones que sólo son aplicables a un editor determinado.  Cuando el editor de archivos readme está activo, observe los 4 botones de barra de herramientas adicionales: Ejecutar extensión de editor Readme, Acción de editor Readme 1, Acción de editor Readme 2 y Acción de editor Readme 3.

Cuando el editor de archivos readme está activo, aparece un menú desplegable denominado Readme.  Contiene las acciones descritas anteriormente: Acción de editor Readme 1, Acción de editor Readme 2 y Acción de editor Readme 3.

Vista Secciones de Readme

Para ver esta vista Secciones de Readme, en el menú Ventana debe seleccionar Mostrar vista, a continuación seleccione Otras... en el submenú.  Expanda el elemento Readme y, a continuación, seleccione Secciones de Readme.  Esta acción mostrará una lista de las secciones que hay en el archivo *.readme actual al seleccionar un archivo .readme en la vista Navegador.  También puede ver la estructura de un archivo *.readme en la vista Esquema.

Un archivo con la extensión .readme puede dividirse en secciones, cada una de las cuales empieza por un número.  Por ejemplo, si se entró el texto siguiente en el editor de archivos readme, la herramienta Readme detectará 2 secciones.  Para ver cómo se detectan las secciones en la herramienta Readme, escriba texto en el editor de archivos readme, guarde el archivo pulsando Control-S o seleccionando  Archivo->Guardar. Abra la vista Secciones de readme y seleccione el archivo .readme en la vista Navegador.

Texto de ejemplo:

99.1 Ésta es mi primera sección
Esto es texto de mi primera sección.

99.1.1 Ésta es una subsección
Esto es texto de mi subsección.

Arrastrar y soltar

La funcionalidad de Arrastrar y soltar puede verse si se selecciona una sección en la vista Esquema y se arrastra la selección encima de un archivo de texto. El contenido de la selección se agregará al archivo.

Contribución de ayuda

El ejemplo de la herramienta Readme también muestra cómo utilizar e implementar ayuda contextual sobre todas las extensiones que proporciona: una vista, diversas acciones y una página de asistente.  Para obtener ayuda contextual sobre una acción, pase el cursor sobre el elemento de menú, pero no lo seleccione, y pulse la tecla F1.  También puede obtener ayuda sensible al contexto (F1) en la vista Secciones de Readme y en la página Asistentes de creación de ejemplos (en el asistente de Nuevo).
 

Detalles

El ejemplo de la herramienta Readme declara un punto de extensión y proporciona varias extensiones.  Las extensiones proporcionadas ayudan a tener una comprensión general sobre cómo funciona el entorno de trabajo, ya que éste utiliza varios de los puntos de extensión más interesantes declarados por el entorno de trabajo.  Las extensiones proporcionadas que se incluyen en este ejemplo son vistas y acciones de vista, páginas de preferencias, páginas de propiedades, asistentes, editores y acciones de editor, menús emergentes, conjuntos de acciones, contribuciones de ayuda, contextos de ayuda y acciones de soltar.

Este ejemplo también proporciona un punto de extensión declarado en el conector. La clase IReadmeFileParser es necesaria para cualquier conector que utiliza la extensión org.eclipse.ui.examples.readmetool.sectionParser que este ejemplo define. La clase DefaultSectionParser es una implementación de ejemplo de IReadmeFileParser.

La clase ReadmeEditor implementa IEditorPart y se define como un editor de archivos con la extensión .readme en plugin.xml mediante el punto de extensión org.eclipse.ui.editors. La clase ReadmeSectionsView implementa IViewPart y se define como una vista utilizando el punto de extensión org.eclipse.ui.views. Además, este punto de extensión define una categoría para la vista que se utilizará en la selección de vista.

En este ejemplo se definen dos tipos de valores de preferencias: preferencias de entorno de trabajo y propiedades de recursos. La preferencia del entorno de trabajo se define en la clase ReadmePreferencePage, que implementa IWorkbenchPreferencePage de manera que se añadirá al diálogo Ventana->Preferencias. La clase se define en el punto de extensión org.eclipse.ui.preferencePages de plugin.xml. Las dos páginas de propiedades de recursos son ReadmeFilePropertyPage y ReadmeFilePropertyPage2 y ambas implementan IWorkbenchPropertyPage. Ambas se definen para invocarse en el tipo IFile con el código objectClass en el punto de extensión org.eclipse.ui.propertyPages de plugin.xml.

La clase ReadmeCreationWizard implementa INewWizard y se define en el punto de extensión org.eclipse.ui.newWizards de plugin.xml. Este punto de extensión también define la categoría que se muestra en el asistente cuando el usuario selecciona Archivo->Nuevo->Ejemplo....

A este ejemplo se añaden varios apéndices de acciones. El conjunto de acciones declara que un menú con la etiqueta Editor de archivos readme debe incluirse en la barra de menús de la ventana del entorno de trabajo utilizando el punto de extensión org.eclipse.ui.actionSets. También define una acción para la barra de herramientas y la barra de menús del entorno de trabajo mediante los códigos toolbarPath y menubarPath. Utiliza la clase WindowActionDelegate que implementa IWorkbenchWindowActionDelegate para implementar la acción. La acción correspondiente al menú emergente se define como un objectContribution mediante la clase PopupMenuActionDelegate en  el punto de extensión org.eclipse.ui.popupMenus. PopupMenuActionDelegate implementa IObjectActionDelegate y utiliza el IWorkbenchPart proporcionado para abrir un diálogo de mensaje. La acción de vista ViewActionDelegate se define en el punto de extensión org.eclipse.ui.viewActions e implementa IViewActionDelegate. La vista en que aparece se define mediante el código targetID que, en este ejemplo, es org.eclipse.ui.views.ResourceNavigator. La acción de editor se define mediante la clase EditorActionDelegate que implementa IEditorActionDelegate y se añade utilizando el punto de extensión org.eclipse.ui.editorActions. El editor al que se aplica se define mediante el código targetID que, en este ejemplo, se define en org.eclipse.ui.examples.readmetool.ReadmeEditor.

La clase ReadmeDropActionDelegate implementa IDropDelegate. IDropDelegates son informados cada vez que se realiza una acción de soltar en el entorno de trabajo. El punto de extensión para esta acción es org.eclipse.ui.dropActions.