NetBeans Platform Cookbook Chapter 02 05

Using Multiview

Some data/objects can be edited or visualized by two (or more) ways. For example:

  • The programmer can edit the GUI form directly as a source or by mouse in the visual representation in known IDEs.
  • Designer can edit source's details or visual representation of 3D objects.
  • Game developer provides create own worlds for 2D and 3D games.
  • Graph data to generate graphs can be visualize as a data-set, table of values or graph for manual manipulation.
  • Each view can display raw data, filtered data, visualize by several manners.

The NetBeans Platform provides framework to assemble, display and switch one data in several panels within TopComponent. To use more TopComponents to manipulate the same data is not intuitive to the user because each component shows different content in most cases. Multiview TopComponent contains inner tabs to switch views, components in tabs and toolbar.


Each view is JComponent (you can use its subclasses, JPanel or even TopComponent). It must implement the MultiViewElement interface.

How to

Create components you want show in view – e. g. MultiViewPanel1 etc. or TextViewPanel, VisualViewPanel.

Implement MultiViewElement interface for each component. You do not need to implement it into corresponding component, you can make special class MultiViewElement1 – it is better because the visual panel is created on demand, its functionality is separated from the component, even the component can be imported from some library or reused elsewhere without dirtying it by this interface.

Implement the getVisualRepresentation() method. Do not create GUI component here. In the documentation is written: “Returns Swing visual representation of this multiview element. Should be relatively fast and always return the same component.” If component implements it then return this.

In getActions() method check if callback is set. If yes add yours actions to actions of parent TopComponent retrieving via callback else return yours. In the getLookup() method return this and objects that you want to add to TopComponent's lookup.

In the setMultiViewCallback(MultiViewElementCallback c) method store callback. It is useful to access the parent TopComponent.

The MultiViewElement interface includes methods known from TopComponent - componentActivated(), componentDeactivated(), componentClosed(). You can call synchronization of the visualized data. Notify the EditorSupport or DataObject about data changes.

In the componentOpened() method you can set TopComponent's name:

        MultiViewElementCallback callb = this.callback;
        if (callb == null) {
        callback.updateName(  // retrieve name e. g. by
              editorsupport.getDataObject().getName() );

In the canCloseElement() method return CloseOperationState.STATE_OK if the user is allowed to close this view. If all views return OK the TopComponent can be closed. If you do not want allow closing return some CloseOperationState object created by MultiViewFactory.createUnsafeCloseState() factory. You must define CloseOperationHandler instance by MultiviewDescriptor creation - see later.

Implement getUndoRedo() functionality or return UndoRedo.NONE.

For each view create MultiViewDescription object which describes view element and creates GUI components. Methods getPersistenceType(), getDisplayName(), getIcon(), getHelpCtx(), preferredID() are known from TopComponents.

The createElement() method is called only once to create visual panel (MultiViewElement) - MultiViewPanel1 in MultiViewDescription1.

In operation opening our multiview create descriptions,

    MultiViewDescription [] mvd = {
              new MultiviewDescription1()
            , new MultiviewDescription2()
        CloseOperationHandler closehandler = 
                                   new CloseHandler();
        TopComponent tc = MultiViewFactory.createMultiView(
                  mvd    // descriptions
                , mvd [1]  // default/first opened
                , closehandler); // handler for closing;

There is left to deal about CloseOperationHandler class. Its method

boolean resolveCloseOperation(CloseOperationState[] elements)

resolves if an element used in a multiview can be closed. It receives CloseOperationState objects from all elements. You can check date here, test if data were saved, if some task is running. You can ask the user to allow close it.

Notes/Tips CloneableEditor

If you use the CloneableEditor in view element you can retrieve the toolbar via document

   JEditorPane edpane = this.pane;
   if (pane != null)  {
      Document doc = pane.getDocument();
      if (doc instanceof NbDocument.CustomToolbar)  {
         toolbar = ((NbDocument.CustomToolbar) doc).
   }  // if (pane != null)
   if (toolbar == null) {
      toolbar = new JToolbar();

Notes/Tips Example sources

As more complex example source examples contain module Town File Support in Multiview project. This example is copied and reduced from KarelNB project and it visualizes Town which the Karel robot runs in. This project is available on

The Karel robot is robot living in the rectangle Town. It is divided into squares, which can contain the robot, the Wall, Signs or nothing. Robot knows basic set of commands: STEP, LEFT, RIGHT, PUT, GET, STOP, Recognizes its direction, the wall in its direction, empty or full field of signs and can define new commands using till known commands and basic programming constructions (if-else, repeat # times, while). Children can learn programming skills by manipulating the robot.

This project is (till not guru-like) example for creating project, DataObject and multiview editor, language support, building NB based application using own stable Platform etc. It will be developed to mature state, I hope.

Important thing for us is the TownPanel (reduced for our example) which is visual view and editor for Town object. We show the raw source and this panel.


Figure 2.9 Text view


Figure 2.10 Visual view

For more information see sources for Chapter 2 - Project Multiview - module Town file support or original KarelNB project.


Text and sources were created under NB 6.8 6.9, 7.0, 7.1, 7.2. TODO null pointer by opening.


Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo