DLTK Mini-HOWTO

Summary

This document contains short notices about how to implement typical end-user features using a DLTK.

Editor

Editors may be contributed as usual using a org.eclipse.ui.editors extenstion point. For all script language editors exists ScriptEditor abstract class. It already has standard editor features like folding support, standard actions, word navigation, bracket matching, outline page and more.

There are important things, that concrete editor implementation should provide. First thing it a "text tools". So you should implement all ScriptTextTools abstract methods. They may return partition scanner, semantic highlighing strategies, source viewer configuration and more.

Source viewer configuration is a second important thing. If you'll use ScriptSourceViewerConfiguration as base, you'll fetch "for free" a quick outline view, documentation hovers, hyperlinks support.

Outline

ScriptEditor has a doCreateOutlinePage() abstract method for creating outline page. Such outline page should extend a ScriptOutlinePage class.

Code folding

ScriptEditor class has methods getFoldingStructureProvider() and createFoldingActionGroup(). In general, folding structure provider should just implement IFoldingStructureProvider. But if you are using a DLTK AST, you can fetch folding "for free", just by extending AbstractASTFoldingStructureProvider.

Folding actions group can be created like following(FoldingActionGroup is a default DLTK implementation):

	protected FoldingActionGroup createFoldingActionGroup() {
		return new FoldingActionGroup(this, getViewer(), RubyUI.getDefault()
				.getPreferenceStore());
	}

Go-to-the-declaration

For go-to-the-declaration feature and many others like documentation hovers you need to implement selection engine. Task of selection engine is to determine model element from given offset in source file.

Selection engines could be contributed via org.eclipse.dltk.core.selectionEngine extension point, they should implement ISelectionEngine interface. DLTK already has partial implementation of this interface: ScriptSelectionEngine, so you could just extend it.

For example implementation, you can look at RubySelectionEngine.

Documentation hovers

Via org.eclipse.dltk.ui.scriptDocumentationProviders extension point you may contribute documentation providers. For that you should implement IScriptDocumentationProvider interface. For given model element or keyword it should return a Reader object with documentation.

After you had implemented it, F2 action and hovers should work. If you rely on model elements, selection engine should be implemented.

Completion and templates

• Implement completion engine. It should extend ScriptCompletionEngine class. Contribute it via org.eclipse.dltk.core.completionEngine extension point.

• Contribute proposal computer via org.eclipse.dltk.ui.scriptCompletionProposalComputer. It should be derived from ScriptCompletionProposalComputer. Inside it you should create a proposal collector and template processor.

Task of proposal collector is to accept completion proposals from completion engine, create appropriate labels for proposals and return as result set of IScriptCompletionProposal. You may use ScriptCompletionProposalCollector as base class for your implementation.

Template processor is a separate implementation of IContentAssistProcessor that should compute proposals for templates. You should use TemplateCompletionProcessor as base class for your implementation.

• Extend ScriptCompletionProcessor and create class for your code completion processor.

• Implement getContentAssistant() method in your source viewer configuration. Example:

public IContentAssistant getContentAssistant(ISourceViewer sourceViewer) {

		if (getEditor() != null) {

			ContentAssistant assistant = new ContentAssistant();
			assistant
					.setDocumentPartitioning(getConfiguredDocumentPartitioning(sourceViewer));

			assistant
					.setRestoreCompletionProposalSize(getSettings("completion_proposal_size")); //$NON-NLS-1$

			IContentAssistProcessor scriptProcessor = new RubyCompletionProcessor(
					getEditor(), assistant, IDocument.DEFAULT_CONTENT_TYPE);
			assistant.setContentAssistProcessor(scriptProcessor,
					IDocument.DEFAULT_CONTENT_TYPE);
		

			RubyContentAssistPreference.getDefault().configure(assistant,
					fPreferenceStore);

			assistant
					.setContextInformationPopupOrientation(IContentAssistant.CONTEXT_INFO_ABOVE);
			assistant
					.setInformationControlCreator(getInformationControlCreator(sourceViewer)); 

			return assistant;
		}

		return null;
	}

Preferences pages

DLTK has a set of abstract classes for preference pages. Here is a list of main of them:

AbstractConfigurationBlockPreferencePage Abstact preference page, that can be used for anything. AbstractConfigurationBlock Abstact configuration block, has implementation of methods like addCheckBox(), addComboBox() with appropriate listeners and linking with preferences. You'll need just to implement createContol() method. AbstractScriptEditorColoringConfigurationBlock Block for syntax coloring preferences. InterpretersBlock Block for interpreters settings. You'll need to implement only getCurrentNature() method and interpreter addition dialog. AddScriptInterpreterDialog Dialog for adding an interpreter.

Search

Simple declaration search will be available automatically, after you specify sourceElementParser for your language and add search pages.

For search pages you need to extend org.eclipse.search.searchPages extension point. There is ScriptSearchPage class, you can use it like following:

public class RubySearchPage extends ScriptSearchPage {
	protected IDLTKLanguageToolkit getLanguageToolkit() {
		return RubyLanguageToolkit.getDefault();
	}
}

For more advanced search you need to perform following tasks:

• Extend org.eclipse.dltk.core.search extension point. It will provide ISearchFactory interface. With this interface you could specify match parser, locator, and source indexer requester.

For example you could see RubySearchFactory or TclSearchFactory classes.

• MatchLocatorParser is used to parse selected module and report all possible matches to pattern locator.

• SourceIndexerRequestor is used to report all needed things to DLTK Index. Default implementation (SourceIndexerRequestor) report model elements.

Launching

• Register installation type for your intepreter using a org.eclipse.dltk.launching.interpreterInstallTypes ext. point. Use a AbstractInterpreterInstallType class as base for implementation.

• Register launch configuration type using a org.eclipse.debug.core.launchConfigurationTypes ext. point. Use a AbstractScriptLaunchConfigurationDelegate as base for your launch delegate implementation.

• Add preference page for interpreter configuration. InterpretersBlock may be used as base for a configuration block. In fact you may use any another way for interpreter configuration, but for launching at least one interpreter should be registered in the workspace and be available for a ScriptRuntime class.

• Also you may add a shortcut for launching via org.eclipse.debug.ui.launchShortcuts. Use AbstractScriptLaunchShortcut as base for your implementation(then you'll should just point a language nature and configuration type inside).