Skip navigation links
org.netbeans.core.multiview/1 1.52

Package org.netbeans.core.spi.multiview

MultiView SPI provides infrastructure for creating components that dock multiple views into one consistent component.

See: Description

Package org.netbeans.core.spi.multiview Description

MultiView SPI provides infrastructure for creating components that dock multiple views into one consistent component. Developers define what shall be included into the component and are given opportunity to influence the overall behaviour of the component.
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.

Persistence

TopComponents decide about persistence based on the TopComponent.getPersistenceType()  return values. Possible values are:
The multiview component decides what it's return value is based on the values returned by MultiViewDescription.getPersistenceType() of all  embedded MultiViewDescriptions. 
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.

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.

Skip navigation links
org.netbeans.core.multiview/1 1.52