A menudo, se espera que un usuario proporcione información de texto en un campo simple, como por ejemplo un campo de texto o un recuadro combinado. Aunque el código de aplicación que puebla estos campos es generalmente mucho más simple que el código que puebla un widget complejo como por ejemplo una tabla o un árbol, normalmente estos campos "simples" aumentan la carga sobre el usuario. El usuario debe identificar qué campos necesitan contenido, si un campo contiene contenido válido y qué opciones se esperan. El soporte de asistencia de campo de JFace proporciona clases que guían al usuario a través de tareas de entrada.
El paquete org.eclipse.jface.fieldassist proporciona asistencia de dos formas. El soporte para los campos decorados permite incluir decoraciones de imagen que indican al usuario el estado de un campo determinado. La Propuesta de contenido permite proporcionar un cuadro emergente de asistencia de contenido que proporciona opciones de contenido para el usuario.
Los campos decorados permiten colocar decoraciones de imagen adyacentes a los campos definidos en una ventana o un diálogo. Las decoraciones pueden colarse junto a una de las cuatro esquinas de un campo. Al igual que los visores, los campos decorados pretenden añadir funcionalidad a un control SWT al tiempo que se proporciona acceso al control subyacente. La API para DecoratedField permite añadir, ocultar y mostrar decoraciones adyacentes a un campo. El acceso al control subyacente se proporciona de forma que puede utilizar la API de SWT existente para afectar al control subyacente, como por ejemplo estableciendo su contenido, color o font.
Desde el exterior, un campo decorado se comporta como un sólo control. Internamente, los campos decorados utilizan un control compuesto para gestionar el diseño del campo y de sus decoraciones. En su mayor parte, esto no debería afectar a la aplicación de cliente. Sin embargo, esto significa que el campo decorado debe realizar la creación real del control. Por ejemplo, fíjese en este fragmento de código en el que una aplicación crea un control de texto dentro de uno de sus diálogos:
... // Crear un campo de texto Text text = new Text(parent, SWT.BORDER); text.setText("Algún texto"); ...
Para decorar este campo, el campo se creará de esta forma:
... // Crear un campo decorado para un control de texto DecoratedField field = new DecoratedField(parent, SWT.BORDER, new TextControlCreator()); Text text = (Text)field.getControl(); text.setText("Algún texto"); ...
Los mismos bits de estilo y padre que se utilizarían para crear el control básico se utilizan también para crear un archivo decorado. La diferencia principal en el código es que se proporciona una instancia de IControlCreator que crea la especie específica de control deseada en el campo. Para los campos de texto puede utilizar la clase TextControlCreator para crear el control. Sin embargo, tiene la flexibilidad de implementar IControlCreator para crear cualquier otra especie de control dentro del campo, como por ejemplo un recuadro combinado o un graduador.
Una vez se ha creado un campo decorado, se le pueden añadir decoraciones en una de cuatro ubicaciones. Las constantes de ubicación SWT se utilizan para especificar dónde debe colocarse la decoración. Para añadir una decoración, debe especificar un FieldDecoration que define la imagen para la decoración y texto descriptivo (opcional) que puede mostrarse cuando el usuario pasa el puntero del ratón sobre la decoración.
... // Crear una decoración de campo y añadirla al campo Image image = JFaceResources.getImage("myplugin.specialimage"); FieldDecoration mySpecialDecoration = new FieldDecoration(image, "Este campo es especial"); field.addFieldDecoration(mySpecialDecoration, SWT.TOP | SWT.LEFT, false); ...
El parámetro booleano se utiliza para especificar si la decoración debe mostrarse solamente cuando el control está enfocado o si debe mostrarse siempre. En este caso, la decoración se mostrará siempre. Sin embargo, puede haber otras ocasiones en las que debe ocultarse o mostrarse la decoración. El fragmento de código siguiente oculta una decoración que ya se ha creado.
... // Se ha producido algo que me hace ocultar la decoración field.hideDecoration(mySpecialDecoration); ...
Si se actualiza la imagen o la descripción de una decoración, debe notificarse al campo para que pueda volver a dibujarse la decoración.
... // Algo ha hecho que el campo sea muy especial mySpecialDecoration.setDescription("Este campo es muy especial"); field.updateDecoration(mySpecialDecoration); ...
Al diseñar un campo decorado dentro de un diálogo o una ventana, puede diseñar el control de diseño del campo en lugar del control simple subyacente. Vuelva a fijarse en el código para crear un control de texto. Al diseñar un control de texto, la aplicación fija datos de diseño en el control.
... // Crear un campo de texto Text text = new Text(parent, SWT.BORDER); text.setText("Algún texto"); // Establecer los datos de diseño GridData data = new GridData(IDialogConstants.ENTRY_FIELD_WIDTH, SWT.DEFAULT); text.setLayoutData(data); ...
Al diseñar un campo decorado, la aplicación debe permitir los datos de diseño en el control de diseño del campo. Según sea el diseño deseado, será necesario ajustar el tamaño del campo al de la decoración.
... // Crear un campo decorado para un control de texto DecoratedField field = new DecoratedField(main, SWT.BORDER, new TextControlCreator()); Text text = (Text)field.getControl(); text.setText("Algún texto"); // Establecer los datos de diseño GridData data = new GridData(IDialogConstants.ENTRY_FIELD_WIDTH + FieldDecorationRegistry.getDefault().getMaximumDecorationWidth(), SWT.DEFAULT); field.getLayoutControl().setLayoutData(data); ...
Para el soporte de asistencia de campo no es necesario que esté utilizando solo campos decorados dentro de un diálogo o una ventana determinados. Sin embargo, es posible que el diseño de la ventana sea un poco más complicado cuando los campos decorados se mezclen con controles simples. Para alinear los campos decorados y no decorados, debe tener en cuenta el sangrado creado por la anchura de la decoración. La anchura de una decoración es simplemente la anchura de su imagen. Sin embargo, las cosas pueden ser más complicadas si está utilizando decoraciones con anchuras diferentes. Si este es el caso, puede simplificar las cosas registrando todas las decoraciones en el FieldDecorationRegistry.
El registro de decoraciones de campo permite registrar y acceder a las decoraciones de campo utilizando un ID de serie. Esto proporciona una forma cómoda de hacer referencia a las decoraciones utilizadas a través de la aplicación. Puede optar por definir la API que expone sus ID de decoración si desea ponerlos a disposición de otros plug-ins. Tenga en cuenta que el registro de una decoración no gestiona el ciclo de vida de las imágenes dentro de esas decoraciones. Su aplicación puede decidir cómo gestionar esas imágenes. Por ejemplo, el registro de imágenes de JFace puede utilizarse para registrar y gestionar el ciclo de vida de la imagen. Su aplicación también puede crear la imagen bajo demanda y deshacerse de ella cuando ya no sea necesaria. El javadoc de los métodos de registro de FieldDecorationRegistry explica las formas diferentes en que las imágenes pueden especificarse al registrar una decoración.
Al registrar las decoraciones en el registro de decoración de campos también se puede simplificar el proceso de diseño al mezclar campos decorados (y no decorados.) Por omisión, un campo decorado consultará el registro de decoración de campos para determinar la anchura máxima de una decoración y se asegurará de que todas las decoraciones utilicen esta anchura. Esto significa que todos los campos decorados se alinearán adecuadamente independientemente de la anchura de una decoración determinada. Para alinear campos no decorados puede utilizar el protocolo FieldDecorationRegistry para acceder a la anchura de la decoración más larga y para crear el sangrado necesario.
... // Crear un campo de texto Text text = new Text(parent, SWT.BORDER); text.setText("Algún texto"); // Establecer los datos de diseño GridData data = new GridData(); data.horizontalAlignment = SWT.FILL; data.horizontalIndent = FieldDecorationRegistry.getDefault().getMaximumDecorationWidth(); text.setLayoutData(data); ...
Aunque el soporte de asistencia de campo no establece cómo deben utilizarse las decoraciones, el registro también define decoraciones estándar que las aplicaciones pueden utilizar para mostrar ciertos estados de un campo. Por ejemplo, el fragmento de código siguiente utiliza una decoración estándar para los campos necesarios:
... // Crear un campo decorado con una decoración de campo necesaria. DecoratedField field = new DecoratedField(main, SWT.BORDER, new TextControlCreator()); FieldDecoration requiredFieldIndicator = FieldDecorationRegistry.getDefault(). getFieldDecoration(FieldDecorationRegistry.DEC_REQUIRED); field.addDecoratedField(requiredFieldIndicator, SWT.BOTTOM | SWT.LEFT, false); ...
Además de anotar los campos con decoraciones, las aplicaciones pueden proporcionar una asistencia de propuestas de contenido que active un cuadro emergente de propuestas para un campo. Puede instalar un ContentProposalAdapter en un control arbitrario para proporcionar este comportamiento. El fragmento de código instala un adaptador de propuesta de contenido en un control de texto. Tenga en cuenta que este control de texto puede ser un control creado directamente por la aplicación o uno obtenido de un campo decorado.
... autoActivationCharacters = new char[] { '#', '(' }; keyStroke = KeyStroke.getInstance("Ctrl+Space"); // suponer que myTextControl ya se ha creado de alguna forma ContentProposalAdapter adapter = new ContentProposalAdapter( myTextControl, new TextContentAdapter(), new SimpleContentProposalProvider(new String [] {"ProposalOne", "ProposalTwo", "ProposalThree"}), keyStroke, autoActivationCharacters);
Para obtener y establecer el contenido del control cuando el usuario elige una propuesta en el cuadro emergente, se debe proporcionar al adaptador una instancia de IControlContentAdapter que puede recuperar y establecer el contenido de una especie de control determinada. Para los campos de texto, puede utilizar la clase TextContentAdapter. Sin embargo, tiene la flexibilidad de implementar IControlContentAdapter para utilizar el adaptador de propuestas de contenido con cualquier otra especie de control.
Al crear un adaptador de propuestas, también debe especificar una instancia de IContentProposalProvider a partir de la cuál se recuperan las propuestas. Este proveedor es responsable de devolver una matriz de propuestas de contenido. Las propuestas se especifican como instancias de IContentProposal a partir de la cuál pueden obtenerse la etiqueta y el contenido de la propuesta, además de otra información como por ejemplo una descripción detallada de la propuesta.
En el ejemplo anterior, se utiliza SimpleContentProposalProvider. Este proveedor se define especificando una matriz simple de Series como las propuestas de contenido. El proveedor simple implementa el protocolo necesario para correlacionar cada serie en la IContentProposal esperada. La flexibilidad de IContentProposalProvider permite implementar un proveedor de propuestas con características avanzadas, como por ejemplo el filtrado de las propuestas basado en el contenido del control, el suministro de etiquetas explicativas en el cuadro emergente en lugar del contenido real que se insertará y la especificación de la posición del cursor esperada después de insertar una propuesta. Consulte el Ejemplo de asistencia de campo y busque implementadores de IContentProposalProvider para una utilización avanzada.
Hemos visto que la definición básica de un adaptador de propuestas de contenido incluye el control para el que se proporcionan las propuestas, el adaptador de contenido utilizado para alterar el contenido del control y el proveedor de propuestas que define la lista de propuestas en el cuadro emergente. Además de estos conceptos básicos, hay muchas formas de configurar el adaptador de propuestas de contenido:
El soporte de asistencia de campo en el nivel de JFace proporciona a la aplicación mucha flexibilidad para determinar cómo decorar campos y mostrar propuestas para el contenido del campo. Esto es deseable para las aplicaciones JFace autónomas o para las aplicaciones de cliente enriquecido autónomas. Sin embargo, si la aplicación va a integrarse con otros plug-ins, como por ejemplo el SDK de Eclipse o plug-ins de otras empresas, querrá utilizar el soporte de asistencia de campo de forma que sea coherente con los otros plug-ins. El entorno de trabajo define las clases de programa de utilidad que utilizan la asistencia de campo para especies de interacciones específicas.
Por ejemplo, la clase ContentAssistField crea un campo que incluye una decoración de bombilla para indicar al usuario que la asistencia de contenido está disponible. También configura un adaptador de propuestas de contenido para la inserción de estilo de asistencia de contenido. Finalmente, proporciona un manejador para el mandato de la asistencia de contenido de nivel de entorno de trabajo de forma que el cuadro emergente de la propuesta de contenido se abre cuando el usuario invoca la secuencia desencadenante o de pulsación de teclas que se ha especificado en los enlaces de teclas del entorno de trabajo. Consulte el paquete org.eclipse.ui.fieldassist para obtener más detalles acerca de estas clases de programa de utilidad.
Se espera que este paquete se desarrolle conforme el entorno de trabajo amplíe su utilización de la asistencia de campo y estandarice la utilización de decoraciones para determinados estados de campo.