Package org.netbeans.core.spi.multiview

This SPI handles the lifecycle of a multiview component.

See:
Description

Interface Summary

CloseOperationHandler	Handles closing of the MultiView component globally.
MultiViewDescription	Description of multi view element.
MultiViewElement	View element for multi view, provides the UI components to the multiview component.
SourceViewMarker	A marker interface for MultiViewDescription instances that allows to identify them as containing source code.

Class Summary

CloseOperationState	instances of this class describe the MultiViewElement's state when the component is about to be closed.
MultiViewElementCallback	Requester type of class, allowing implementors of MultiViewElement to send requests back to enclosing component and window system.
MultiViewFactory	Factory class for creating top components handling multi views.

Package org.netbeans.core.spi.multiview Description

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 MultiViewDescriptions 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 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 MultiViewElement.canCloseElement(). The owner of the multiview component resolves the problems (silently or by asking the user) in CloseOperationHandler.resolveCloseOperation(org.netbeans.core.spi.multiview.CloseOperationState[])

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 MultiViewDescription instances get serialized. Thus they need to implement Serializable. Then for all MultiViewDescriptions that were opened (created their 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 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 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 CloseOperationHandler.resolveCloseOperation(org.netbeans.core.spi.multiview.CloseOperationState[]) method implementation.