Contenthulp

Contenthulp geeft gebruikers de mogelijkheid om contextgevoelige contentaanvulling op te vragen. Deze functionaliteit wordt geïmplementeerd door het platformtekstframework in org.eclipse.jface.text.contentassist. In voorgrondvenster (infovensters) worden de beschikbare keuzemogelijkheden voor aanvulling van een stuk tekst afgebeeld. De gebruiker kan deze selecteren en in de tekst invoegen. Contenthulp ondersteunt ook contextgevoelige infovensters voor de gebruiker met informatie die is gerelateerd aan de huidige positie in het document. 

Het implementeren van contenthulp is optioneel. Standaard wordt bij SourceViewerConfiguration geen contenthulp geïnstalleerd omdat niet automatisch kan worden bepaald welk documentmodel voor een bepaalde editor wordt gebruikt en er geen algemeen gedragspatroon voor contenthulp is. 

Om contenthulp te implementeren, moet de bronviewer voor uw editor worden geconfigureerd met een contenthulpprogramma. In het Java-editorvoorbeeld gebeurt dit in JavaSourceViewerConfiguration.

public IContentAssistant getContentAssistant(ISourceViewer sourceViewer) {

	ContentAssistant assistant= new ContentAssistant();
	assistant.setContentAssistProcessor(new JavaCompletionProcessor(), IDocument.DEFAULT_CONTENT_TYPE);
	assistant.setContentAssistProcessor(new JavaDocCompletionProcessor(), JavaPartitionScanner.JAVA_DOC);

	...
	return assistant;
}

Het gedragspatroon van contenthulp wordt gedefinieerd in de interface IContentAssistant.  Het instellen van een contenthulpprogramma is min of meer vergelijkbaar met het instellen van accentuering voor syntaxis. De hulp moet worden geconfigureerd met verschillende contentaanvullingsstrategieën voor verschillende documentcontenttypen. De aanvullingsstrategieën worden geïmplementeerd met  IContentAssistProcessor. Een verwerkingsprogramma stelt aanvullingen voor en berekent contextinformatie voor een offset binnen een bepaald contenttype.

Verwerkingsprogramma's voor contenthulp

Niet alle contenttypen hoeven gekoppeld te zijn aan contenthulp. In de Java-voorbeeldeditor zijn er wel verwerkingsprogramma's gedefinieerd voor contenthulp voor het standaardcontenttype en javadoc, maar niet voor commentaar dat uit meerdere regels bestaat. Hieronder vindt u een beschrijving van deze verwerkingsprogramma's.

De JavaCompletionProcessor is relatief eenvoudig. Hiermee kunnen alleen sleutelwoorden worden voorgesteld als beschikbare aanvullingen. De sleutelwoorden worden gedefinieerd in het veld fgProposals en worden altijd voorgesteld als beschikbare aanvullingen:

public ICompletionProposal[] computeCompletionProposals(ITextViewer viewer, int documentOffset) {
	ICompletionProposal[] result= new ICompletionProposal[fgProposals.length];
	for (int i= 0; i < fgProposals.length; i++) {
		IContextInformation info= new ContextInformation(fgProposals[i], MessageFormat.format(JavaEditorMessages.getString("CompletionProcessor.Proposal.ContextInfo.pattern"), new Object[] { fgProposals[i] })); //$NON-NLS-1$
		result[i]= new CompletionProposal(fgProposals[i], documentOffset, 0, fgProposals[i].length(), null, fgProposals[i], info, MessageFormat.format(JavaEditorMessages.getString("CompletionProcessor.Proposal.hoverinfo.pattern"), new Object[] { fgProposals[i]})); //$NON-NLS-1$
	}
	return result;
}

Sleutelwoordcontenthulp

De aanvulling kan handmatig worden geïnitieerd op verzoek van de gebruiker, of automatisch wanneer het teken "(" of "." wordt getypt:

public char[] getCompletionProposalAutoActivationCharacters() {
	return new char[] { '.', '(' };
}

Behalve aanvullingsvoorstellen is in de JavaCompletionProcessor contextinformatie gedefinieerd die door de gebruiker kan worden opgevraagd. Contextinformatie bestaat uit een beschrijving van de beschikbare stukken informatie voor een bepaalde context en een gedetailleerd informatiebericht.  

In het Java-editorvoorbeeld is de informatie niet werkelijk contextueel. Wanneer de gebruiker contextinformatie opvraagt, wordt voor de huidige offset een array met vijf soortgelijke contextinformatie-objecten berekend. Voor al deze contextinformatie-objecten is een context gedefinieerd met de vijf tekens vóór de offset en de vijf tekens na de offset. Als een van deze vijf voorstellen wordt geselecteerd, wordt de gedetailleerde informatie net zo lang nabij de cursor afgebeeld als de cursor zich binnen de context van de vijf tekens voor of na de offset bevindt.

public IContextInformation[] computeContextInformation(ITextViewer viewer, int documentOffset) {
	IContextInformation[] result= new IContextInformation[5];
	for (int i= 0; i < result.length; i++)
		result[i]= new ContextInformation(
			MessageFormat.format(JavaEditorMessages.getString("CompletionProcessor.ContextInfo.display.pattern"), new Object[] { new Integer(i), new Integer(documentOffset) }),
			MessageFormat.format(JavaEditorMessages.getString("CompletionProcessor.ContextInfo.value.pattern"), new Object[] { new Integer(i), new Integer(documentOffset - 5), new Integer(documentOffset + 5)}));
	return result;
}

Java-contexthulp

 

Deze contextinformatie wordt automatisch afgebeeld wanneer het teken "#" wordt getypt:

public char[] getContextInformationAutoActivationCharacters() {
	return new char[] { '#' };
}

Contenthulp configureren

De presentatie en het gedragspatroon van contenthulp kan worden geconfigureerd met IContentAssistant. U bijvoorbeeld de timeout voor automatische activering en de oriëntatie en kleur van informatievensters configureren.

public IContentAssistant getContentAssistant(ISourceViewer sourceViewer) {

	ContentAssistant assistant= new ContentAssistant();
	...
	assistant.enableAutoActivation(true);
	assistant.setAutoActivationDelay(500);
	assistant.setProposalPopupOrientation(IContentAssistant.PROPOSAL_OVERLAY);
	assistant.setContextInformationPopupOrientation(IContentAssistant.CONTEXT_INFO_ABOVE);
	assistant.setContextInformationPopupBackground(JavaEditorEnvironment.getJavaColorProvider().getColor(new RGB(150, 150, 0)));

	return assistant;
}

Maak de contenthulpactie en verbindt deze met een toetskoppeling.

Om gebruikers in staat te stellen om contenthulp op te roepen, moet een actie worden gemaakt en geconfigureerd. Dit wordt normaal gedaan in de subklasse-implementatie van AbstractTextEditor.createActions():

protected void createActions() {
	...
	IAction action= new ContentAssistAction(aResourceBundle, "ContentAssistProposal.", this); //$NON-NLS-1$
	action.setActionDefinitionId(ITextEditorActionDefinitionIds.CONTENT_ASSIST_PROPOSALS);
	setAction(actionId, action); //$NON-NLS-1$
	markAsStateDependentAction(actionId, true); //$NON-NLS-1$
	PlatformUI.getWorkbench().getHelpSystem().setHelp(action, helpContextId);
	...
}
De actiebalkcontributor van de editor moet worden uitgebreid om de actie in het hoofdmenu te laten verschijnen:
...
private RetargetTextEditorAction fContentAssist;

public MyEditorActionContributor() {
	fContentAssist= new RetargetTextEditorAction();
	String commandId= ITextEditorActionDefinitionIds.CONTENT_ASSIST_PROPOSALS;
	fContentAssist.setActionDefinitionId(commandId);
}

public void contributeToMenu(IMenuManager menu) {
	IMenuManager editMenu= menu.findMenuUsingPath(M_EDIT);
	editMenu.appendToGroup(MB_ADDITIONS, fContentAssist);
}

public void setActiveEditor(IEditorPart part) {	IAction editorAction= getAction(part, "ContentAssist");
	fContentAssist.setAction(editorAction);
}
...