|
This SPI handles the lifecycle of a multiview component.
Creation
New instance of MultiView TopComponent can be created by calling
MultiViewFactory.createMultiView
The resulting TopComponent can be docked in arbitrary mode at your
convenience. The factory method requires an array of
{@link org.netbeans.core.spi.multiview.MultiViewDescription}s that
describe the content of the view.
Each description in the View shall have a unique display name
and preferredId.
All the descriptions shall be lightweight classes, which create the
actual visual components on demand in
{@link org.netbeans.core.spi.multiview.MultiViewDescription#createElement}
The multiview component is cloneable by default. If any of your
embedded elements cannot be cloned, or you don't intend to allow the
users to clone the component, please use the appropriate factory method
to create a non-cloneable instance.
Lifecycle
Once the multiview component is opened, the element for the default
MultiViewDescription is created. Creation of other Elements is delayed
to the moment these are required.
All created Elements get notified of changes in the lifecycle of the
multiview component and their own. The notification callback method
have the same name and similar semantics as the TopComponent ones.
- When the element is shown for the first time, componentOpened()
is called.
- Everytime the element is selected in the component,
componentShowing() is called on the new selection and componentHidden()
on the one deselected.
- When focusing the whole component, the currently selected element
receives componentActivated(). When switching elements, the element
loosing focus gets called componentDeactivated(), the one gaining focus
is called componentActivated()
- Whenever the multiview component gets notified of it's state
changes (showing/hidden/activate/deactivated) by the window system,
these are propagated to the currently selected element only.
- For all elements that were created during the lifecycle of the
component, componentClosed() is called when the component is about to
be closed. Closing the component is special because the elements can be
in non-deterministic state and a dataloss situation is possible.
Each created MultiViewElement is queried for it's state, the
environment calls
{@link org.netbeans.core.spi.multiview.MultiViewElement#canCloseElement}.
The owner of the multiview component resolves the problems (silently or
by asking the user) in
{@link org.netbeans.core.spi.multiview.CloseOperationHandler#resolveCloseOperation}
Persistence
TopComponents decide about persistence based on the TopComponent.getPersistenceType()
return values. Possible values are:
- TopComponent.PERSISTENCE_ALWAYS,
- TopComponent.PERSISTENCE_NEVER,
- TopComponent.PERSISTENCE_ONLY_OPENED.
The multiview component decides what it's return value is based on the
values returned by MultiViewDescription.getPersistenceType()
of all embedded MultiViewDescriptions.
- When at least one of
them returns PERSISTENCE_ALWAYS, it is returned by
the TopComponent as well.
- If at least one requires
PERSISTENCE_ONLY_OPENED and none needs PERSISTENCE_ALWAYS, the
TopComponent's state will be stored only when it's opened on IDE exit.
- The multiview topcomponent is not persisted if all descriptions
return PERSISTENCE_NEVER, or any of the descriptions are not
serializable.
In other words, ALWAYS has higher priority than ONLY_OPENED and NEVER
has the lowest priority of all.
When the multiview's TopComponent gets persisted, all of it's
{@link org.netbeans.core.spi.multiview.MultiViewDescription} instances
get serialized. Thus they need to implement Serializable. Then
for all MultiViewDescriptions that were opened (created their
{@link org.netbeans.core.spi.multiview.MultiViewElement} instances) and don't
declare PERSISTENCE_NEVER in their getPersistenceType() method, the
MultiViewElement instance gets persisted as well.
Note: If any of the MultiViewDescription instances is not Serializable,
the TopComponent will not get persisted. Please note that even if your
MultiViewDescription returns PERSISTENCE_NEVER, it should be possible
to serialize the Description instance. After restoration the
deserialized instance will create a fresh MultiViewElement instance.
If you define your own {@link org.netbeans.core.spi.multiview.CloseOperationHandler} implementation for the multiview component, then you also ought to define it
Serializable.
When restoring the multiview TopComponent, all the
MultiViewDescriptions are deserialized, also all the stored
MultiViewElements are deserialized. These are kept and the
createElement() method is not called on the matching
MultiViewDescription.
Manipulating the multiview
MultiViewElements get a chance to manipulate the enclosed topcomponent.
Each of them is passed an instance of
{@link org.netbeans.core.spi.multiview.MultiViewElementCallback} on
creation or deserialization. (Please don't serialize with your
element's data, for performance reasons) It can be used during
lifecycle of the element.
- To request activation.
- To request visibility.
- To get the default topcomponent actions (shall be used to
contruct the Element's getActions() array).
- To change the title for the topcomponent.
If your MultiViewElement is a TopComponent or provides a TopComponent
in getVisualRepresentation(), you can manipulate
the activatedNodes of the whole multiview component by setting the
appropriate nodes on your own TopComponent.
when elements are switched, the activated nodes get updated as well
according to the shown element.
Embedding editors
A typical MultiViewElement for embedding editor extends
CloneableEditor
and delegates some of the functionality to the multiview component.
The multiview component implements CloneableEditorSupport.Pane and the
CloneableEditorSupport instance's createPane() method
shall return the overall multiview component, rather than the
MultiViewElement's component. In such case the opening the component
shall be always done using the openCloneableTopComponent() call which
will register the MultiView component as
a holder of the editor pane for that CloneableEditorSupport instance.
The multiview component will always
delegate to the currently selected element when communication with the
editor support classes. Keep that in mind when trying to manipulate
the editor pane. Always switch to the editor's element first.
Please note: The multiview component is just a placeholder for the
enclosed components. Any data related synchronizations are to be
performed in the client code. This is especially important when
multiple elements work over the same data/files.
At
least the requestActive() and requestVisible() methods shall be
overriden to delegate to the MultiViewElementCallback. Sample code:
public void requestActive() {
if
(multiViewCallback != null) {
multiViewCallback.requestActive();
}
else {
super.requestActive();
}
}
Since TopComponent's lifecycle callback methods (componentOpened(),
componentShowing() etc) are defined with protected scope, you will have
to redefine the to be public to be in synch with the MultiViewElement
interface signature. If the lifecycle within the multiview component
differs from the default behaviour, additional handling goes here as
well.
To create the editor's toolbar, the one provided by the
NbDocument.CustomToobar is the obvious choice.
public JComponent
getToolbarRepresentation() {
if
(toolbar == null) {
JEditorPane pane = getEditorPane();
if (pane != null) {
Document doc = pane.getDocument();
if (doc instanceof NbDocument.CustomToolbar) {
toolbar = ((NbDocument.CustomToolbar)doc).createToolbar(pane);
}
}
if (toolbar == null) {
//attempt to create own toolbar?
toolbar = new JPanel();
}
}
return toolbar;
}
The owner/creator of the multiview component is responsible to handle
proper closing of the editor via the
{@link org.netbeans.core.spi.multiview.CloseOperationHandler#resolveCloseOperation}
method implementation.
|