Contributing to the UI
last modified on Jul 28, 2015
Contributing to the graphical user interface basically works analogous to standard Eclipse — see the Eclipse Platform Developers' Guide for more information on that. This section lists some of the TextGridLab specifics.
Contributing to Menus and Toolbars
The TextGridLab features a Tools menu and a corresponding toolbar in
which your tool should appear. To do so, you should contribute a command
that opens your tool in some way – typically this means switching to a
dedicated perspective and maybe opening some parts. Contribute your
command to the menu
tools and to the perspectives bar.
excerpts, as examples from the CollateX plugin (you'll want to use
Eclipse's graphical editor for the plugin.xml to create these entries!):
<menuContribution allPopups="false" locationURI="toolbar:perspectivesbar"> <command commandId="info.textgrid.lab.collatex.openPerspective" style="push"> </command> </menuContribution> <menuContribution allPopups="false" locationURI="toolbar:perspectivesbar"> <command commandId="info.textgrid.lab.collatex.openPerspective" style="push"> </command> </menuContribution>
Another typical use case is to add a command to the context menu of
TextGrid objects, e.g., in the navigator or in the search results view.
To do so, you can use Eclipse's expression syntax for the
and check for adaptability to
TextGridObjects. Here is an excerpt from
the import tool's
plugin.xml that adds entries to context menus
whenever one or more TextGrid objects are selected:
<extension point="org.eclipse.ui.menus"> <menuContribution allPopups="false" locationURI="menu:file?after=file.anchor6"> <command commandId="info.textgrid.lab.core.importexport.import" mnemonic="%command.mnemonic.import" style="push"> </command> <command commandId="info.textgrid.lab.core.importexport.export" mnemonic="%command.mnemonic.export" style="push"> </command> </menuContribution> <menuContribution locationURI="popup:org.eclipse.ui.popup.any?after=popup.anchor2"> <command commandId="info.textgrid.lab.core.importexport.export" mnemonic="%command.mnemonic.export.1" style="push"> <visibleWhen> <iterate ifEmpty="false" operator="or"> <or> <adapt type="info.textgrid.lab.core.model.TextGridObject"> </adapt> <adapt type="info.textgrid.lab.core.aggregations.ui.model.Aggregation"> </adapt> </or> </iterate> </visibleWhen> </command> </menuContribution> </extension>
In the associated handler, you can then get the selection from the event
and adapt the contents of the
in order to deal with them. An examplary handler that deals with quite
some cases is the one from the Export tool.
This handler already contains quite some complex handling: It first
checks whether the selected object is an Import/Export specification
(and if so, just opens it in the Export editor). Otherwise, it checks
whether we already have an export editor open: If so, the selected
objects are added to that, otherwise, a new editor is created and the
selected objects are added.
Dealing with your own kind of object
If your use case includes to offer an own, project specific kind of object and the appropriate tools to edit these objects, then you'll probably want to define your own TextGrid content type (similar to a MIME type), a corresponding Eclipse content type and an editor that deals with that.
The TextGrid content type is responsible for registering your format and providing the TextGridLab-specific properties. Have a look at the CollateX content type for collation sets as an example. If you use Eclipse's plugin manifest editor to add this, you'll get additional help in its tooltips.
If you have added these three definitions to your
content type will also appear in the New Object dialog. The default
action when the user selects your content type in the New Object
dialog will be to create a new object of your content type and open it
in your editor. Your editor will also be available in the corresponding
context menu of objects of your content type and it will be opened by
default on double-clicking existing objects of your content type.
If possible, you should define your editor as a standard
that deals with
IFileEditorInputs. If you do so, you will also get
appropriate locking behaviour without having to do anything for that.
While your user works on an object, that object should be locked. As long as a user holds a lock on the object, other users' attempts to lock the object fail with a message indicating the user who has the lock, and other users will not be able to modify the object.
The TextGridLab will automatically lock and unlock objects for a
user as long as (1) the object is edited in an editor derived from
EditorPart and registered in the usual Eclipse mechanism, and (2)
the Editor's input is an
IFileEditorInput that corresponds to (and
thus adapts to)
Otherwise, use the LockingService to manually lock and unlock the object. Please note that, for reasons of liveliness, the server side lock by TG-crud will only last for 30 minutes, the object needs to be relocked during that period. The TextGridLab's locking service will do that for you automatically.
Please note that locking is not strictly required, it is mainly a fail fast mechanism. If a user tries to update an object that someone else modified in the meantime, TG-crud will throw an UpdateFault and the user might be in a situation where he either cannot save his modifications or reloads the metadata and overwrites the other person's changes. Locking will cause the process to fail before the user makes any modifications.