Ajuda à passagem do rato para texto e réguas

O suporte de ajuda à passagem do rato é fornecido no quadro de texto da plataforma o que permite implementar ajudas informativas (ou infopops) sobre o texto e as réguas mostrados no editor.

O suporte de ajuda à passagem do rato é opcional.  Por predefinição, a SourceViewerConfiguration não instala comportamento de ajuda à passagem do rato dado que não há informações gerais úteis para mostrar.  Para poder facultar implementar ajuda à passagem do rato no texto ou na régua, a configuração do visualizador de fonte do editor deve ser configurada para definir um objecto de ajuda à passagem do rato que constitua plug-in.

Voltaremos à JavaSourceViewerConfiguration para ver quais os métodos que definem o comportamento da ajuda à passagem do rato:

public ITextHover getTextHover(ISourceViewer sourceViewer, String contentType) {
	return new JavaTextHover();
}
public IAnnotationHover getAnnotationHover(ISourceViewer sourceViewer) {
	return new JavaAnnotationHover();
}

Também podem ser instaladas dinamicamente classes ajudantes de ajuda à passagem do rato com o protocolo SourceViewer (setTextHover e setAnnotationHover). Não há vantagens de tempo de execução numa das formas, mas colocar todas as sobreposições de comportamento de plug-in numa subclasse de SourceViewerConfiguration traz a vantagem de consolidar todas as definições em um só sítio.

Vejamos os pormenores de ambos os tipos de ajuda à passagem do rato.

Ajuda à passagem do rato para texto

A ajuda à passagem do rato para texto permite facultar texto informativo sobre o texto mostrado no editor.  Tal realiza-se com a interface ITextHover.  Uma ajuda à passagem do rato para texto é responsável por calcular a região que deve ser usada como fonte das informações de ajuda, dada uma deslocação no documento.  Também é responsável por facultar o texto informativo sobre determinada região.  A JavaTextHover é muito simples.  Verifica se a deslocação indicada para a ajuda à passagem do rato está contida na selecção de texto.    Se assim for, faculta o intervalo de selecção como região de ajuda à passagem do rato.  

public class JavaTextHover implements ITextHover {

	...
	
	public IRegion getHoverRegion(ITextViewer textViewer, int offset) {
		Point selection= textViewer.getSelectedRange();
		if (selection.x <= offset && offset < selection.x + selection.y)
			return new Region(selection.x, selection.y);
		return new Region(offset, 0);
	}
}

Dada a sua região de ajuda à passagem do rato calculada, obtém o texto seleccionado do respectivo documento e devolve-o como informações de ajuda à passagem do rato.

public class JavaTextHover implements ITextHover {

	public String getHoverInfo(ITextViewer textViewer, IRegion hoverRegion) {
		if (hoverRegion != null) {
			try {
				if (hoverRegion.getLength() > -1)
					return textViewer.getDocument().get(hoverRegion.getOffset(), hoverRegion.getLength());
			} catch (BadLocationException x) {
			}
		}
		return JavaEditorMessages.getString("JavaTextHover.emptySelection"); 
	}
	...
}

É claro que, se passarmos o rato sobre uma selecção no editor, o texto da ajuda à passagem do rato mostra a selecção.

Informações de ajuda à passagem do rato na região seleccionada

Podem ser utilizadas informações contextuais mais complicadas para calcular informações úteis de ajuda à passagem do rato.  Os exemplos encontram-se na JavaTextHover implementada com o editor das JDT.

Ajuda à passagem do rato para réguas

A ajuda à passagem do rato na régua vertical é útil para mostrar informações orientadas por linhas.   A classe de ajuda à passagem do rato é configurada como se descreveu supra.   IAnnotationHover é a interface para objectos de ajuda à passagem do rato para réguas.  Embora o nome indique que a ajuda à passagem do rato está concebida para anotações na régua, na verdade compete a um editor individual determinar o que é apropriado.  Uma ajuda à passagem do rato para réguas é responsável por devolver a cadeia de informações associada a determinado número de linha, independentemente da presença de marcadores nessa linha.    

A JavaAnnotationHover do editor exemplo Java implementa ajuda à passagem do rato para todas as linhas.  Utiliza o número da linha para obter todo o texto na linha de ajuda à passagem do rato e devolvê-lo como cadeia de informações.

public String getHoverInfo(ISourceViewer sourceViewer, int lineNumber) {
	IDocument document= sourceViewer.getDocument();

	try {
		IRegion info= document.getLineInformation(lineNumber);
		return document.get(info.getOffset(), info.getLength());
	} catch (BadLocationException x) {
	}
	return null;
}

Informações de ajuda à passagem do rato na régua

Dado que a ajuda à passagem do rato tem acesso ao documento e ao visualizador de fonte, dispõe de todo o contexto necessário para tomar decisões contextuais mais complicadas sobre as informações que devem ser apresentadas.  Por exemplo, o modelo de anotações pode ser obtido do visualizador de fonte para poder facultar informações de ajuda à passagem do rato para quaisquer anotações mostradas na régua vertical.  A JavaAnnotationHover facultada pelo editor das JDT faculta esta capacidade.