See the Overview for the current architecture and usage hints. Please also see the Javadocs.
This section is partly out of date.
TextGridObjects are unique, i.e. there is never more than one TextGridObject per referable object in TextGrid.
TextGridObject
does not have a public constructor. The
preferred mode of getting one is to adapt an existing representation
of the object to TextGridObject.class
.
Alternatively, you may call one of the factory functions
TextGridObject.create
, which take either
an URI or a metadata block.
Modifying Metadata works as follows:
Metadata and their corresponding objects are tightly coupled. If
you (re-)load an object's contents (e.g. IFile.getContents()
), the metadata is (re-)loaded
from the Grid. If you save an object to the grid, its metadata
will be saved, as well; and the TextGridObject will be updated
with the metadata from the grid). Additionally, it is possible to save only the
metadata.
When objects are created, the following phases are possible:
When the object's metadata is not yet complete or the object has
not been stored to the grid for some other reason, it does not
have its final textgrid:
URI. Instead, the object
is assigned a temporary URI by calling TextGridObject#create(OMElement)
or
TextGridObject#create(). This temporary URI has the form
textgrid-temp:42
.
TGcrud#create
) When you first save the object (either by calling
ITextGridObject.saveMetadata()
or
IFile.setContents(...)
) we need the additional
metadata provided. If it is, TGcrud#create is called with the
metadata and (optionally) the data.
TGcrud#create returns with a new URI from the
textgrid:
scheme. The TextGridObject stays the
same, the IFile's link is modified. Clients addressing the
TextGridObject with the “old” URI (from textgrid-temp:) will
still receive the TextGridObject, nut the latter's
getURI()
method will return the new URI (this
works by adding a link from the new URI to the registry
instead of replacing the temporary URI).
The API for saving files leaves the Save as … functionality basically to the individual editors: There are methods ISaveablePart#doSave(IProgressMonitor) and ISaveablePart#doSaveAs(). doSave saves the IEditorInput, ie it usually calls IFile#setContents, which will result in an IFileStore#openOutputStream and consecutive save operations. With doSaveAs, it's up to the editor to invoke a »Save as …« dialog.
If it is not possible to hijack the general save-as dialog, I suggest that we implement the save as functionality separately, controlled from the EFS layer. I.e., the EFS layer pops up a dialog asking for the new metadata:
File → Save to new TextGridObject …
TextGridObject(activeEditor.getEditorInput).saveAs := true
activeEditor.doSave()
This will finally result in a call to TGFileStore.openOutputStream(), in which:
if TextGridObject(this).saveAs then newMetadata := showMetadataWizard(TextGridObject(this), NEW_VERSION) TGcrud.create(newMetadata, this)
Now we must tell the EditorPart that it is working with a different object now, since it wouldn't expect that. Options are:
createLink(newURI))
. Maybe we also have
to fire a “resource changed” event or something like that.
Disadvantage: This is not intuitive, because the user then
works with a different file, but not with a different file
representation in the GUI.