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.
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.
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.
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; }
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.