How to use WebDocumentPane

Available since: WebLaF v1.28 release
Required Java version: Java 6 update 30 or any later
Module: ui

---

What is it for?

Document pane (or WebDocumentPane) is a set of combined tabbed panes built upon custom document data provided into WebDocumentPane. Under custom document data you should understand DocumentData class or any extending class.

All documents added into WebDocumentPane will have their own DocumentData instance represing the document and will also be assigned to one of existing tabbed panes.

---

What should I know about it?

There are just a few objects used within WebDocumentPane you might want to be familiar with:

• DocumentData - custom document data
• PaneData - object referring existing tabbed pane and containing a list of documents opened inside
• SplitData - object referring existing split pane
• StructureData - abstract interface implemented by PaneData and SplitData

WebDocumentPane uses those objects to build a tree-like components structure which gets deeper with more splits added.

DocumentData

DocumentData class simply contains all base settings you might want to provide for each document tab such as:

• id - this is what simple tabbed pane lacking in most of times
• icon - icon which set directly onto the document tab
• title - document title or language key which is set directly onto the document tab
• background - custom document tab and tab content background
• closeable - whether this document tab can be closed or not
• component - document tab content

Since WebDocumentPane signature looks like this:

public class WebDocumentPane<T extends DocumentData>

you can use your own data class build upon DocumentData easily since all WebDocumentPane, PaneData and SplitData methods will honor your custom data type. This approach is generally similar to tree nodes.

PaneData

It is less likely that you will have to use this class except the cases when you need to navigate the actual structure of WebDocumentPane splits. PaneData contains reference to WebTabbedPane used to display document tabs and references to all opened documents.

It also has a set of methods which can be called to force an additional split or merge. These methods are used in the document tab menu though and can be easily accessed from the UI.

SplitData

It is not likely that you will have to use this class as well for the same reasons as the PaneData. SplitData contains references to actual WebSplitPane component and two components contained inside of it. Those can be either another SplitData or PaneData. This is basically how a tree-like structure is built.

Current root of WebDocumentPane can always be requested from WebDocumentPane itself:

public StructureData getStructureRoot ()

StructureData

This is a simple interface used to reference either PaneData or SplitData in some cases. It also contains some default methods all implementing classes should have.

---

How to use it?

Usage of WebDocumentPane is pretty simple and straightforward - you should simply create its new instance and then just open/close/modify documents you want to see inside of it.

Here is a brief example:

public class DocumentPaneTest
{
    public static void main ( final String[] args )
    {
        WebLookAndFeel.install ();

        final WebDocumentPane pane = new WebDocumentPane ();

        final ImageIcon icon = WebLookAndFeel.getIcon ( 16 );
        pane.openDocument ( new DocumentData ( "some.doc", icon, "Test1", Color.WHITE, new WebLabel () ) );
        pane.openDocument ( new DocumentData ( "other.doc", icon, "Test2", null, new WebLabel () ) );
        pane.openDocument ( new DocumentData ( "total.doc", icon, "Test3", null, new WebLabel () ) );
        pane.openDocument ( new DocumentData ( "less.doc", icon, "Test4", null, new WebLabel () ) );

        pane.setPreferredSize ( new Dimension ( 500, 400 ) );
        TestFrame.show ( pane );
    }
}

And the result:

WebDocumentPane behavior can be easily modified to fit your needs, here are some of the base settings:

pane.setCloseable ( false );
pane.setSplitEnabled ( false );
pane.setTabMenuEnabled ( false );
pane.setDragEnabled ( true );
pane.setDragBetweenPanesEnabled ( false );

Documents opened within WebDocumentPane can be referenced both directly and through their ID:

pane.setSelected ( "my.document.id" );        
pane.getPane ( "my.document.id" ).activate ();        
pane.closeDocument ( myDocument );

You can also customize tabbed panes:

pane.setTabbedPaneCustomizer ( new Customizer<WebTabbedPane> ()
{
    @Override
    public void customize ( final WebTabbedPane tabbedPane )
    {
        // Customize it here
    }
} );

Here are some other handy methods:

final List<DocumentData> documents = pane.getDocuments ();
final DocumentData document = pane.getSelectedDocument ();
final int documentsCount = pane.getDocumentsCount ();

final List<PaneData> allPanes = pane.getAllPanes ();
final PaneData activePane = pane.getActivePane ();

final List<SplitData> allSplitPanes = pane.getAllSplitPanes ();

There is also a document listener available:

pane.addDocumentListener ( new DocumentListener ()
{
    @Override
    public void opened ( final DocumentData document, final PaneData pane, final int index )
    {
        // Document opened
    }

    @Override
    public boolean closing ( final DocumentData document, final PaneData pane, final int index )
    {
        // Document is closing, return false to abort
        return false;
    }

    @Override
    public void closed ( final DocumentData document, final PaneData pane, final int index )
    {
        // Document was closed
    }
} );

---

Save/restore state [ since v1.29 ]

There are several options to save/restore WebDocumentPane state. Under state I mean opened documents position inside the WebDocumentPane components structure and some other visual settings.

You can retrieve/set state manually:

final DocumentPaneState state = pane.getDocumentPaneState ();

pane.setDocumentPaneState ( state );

Or simply register your WebDocumentPane in SettingsManager, for example:

pane.registerSettings ( "DocumentPaneTest", "state" );

This will save your WebDocumentPane state in a separate settings group automatically on changes (unless that option - autosave on changes - is switched off). You can also force settings save action:

pane.saveSettings ();

Though that will work only if you have already registered your WebDocumentPane in SettingsManager.

One more important thing about this feature - in case you are restoring the state - you might want to have all documents be already opened at that moment or set DocumentDataProvider into your WebDocumentPane, otherwise state won't be able to restore documents properly and you might not see some of them opened.

Here is an example how you can set DocumentDataProvider:

pane.setDocumentsProvider ( new DocumentDataProvider ()
{
    @Override
    public DocumentData provide ( final String documentId )
    {
        return new DocumentData ( documentId, ... );
    }
} );

Basically this provider can replace manual documents open process and will do that on its own. Though it is up to you to choose how you want to do that part.

---

Well, seems thats all about basics of WebDocumentPane usage.

Something might be missing but I am always opened for suggestions - if you are actually missing some feature or method simply post your suggestion here: https://github.com/mgarin/weblaf/issues/new