Since byte-welt.de is currently offline, the forum is temporarily relocated to Github.

Where can I find more help?

Visit our forum Byte-Welt.

What do I need?

The framework requires Java 1.5, the glass extension requires Java 1.6. You also need to download the framework, the jar files "docking-frames-core.jar" and "docking-frames-common.jar" have to be included in the classpath of your application.

Should I use the stable version or the head?

I suggest you stick to the head and keep updating the framework. That way you always have the newest bugfixes. The biggest difference between a stable and an unstable version is the documentation, it is often outdated for unstable versions.

Are there any examples?

There is a set of small examples in the "tutorial" project. Start the application "tutorial.jar" (or its main-class "tutorial.TutorialMain") to get a list of all available examples. You can also just press the launch button below (this version may however not always be up to date).

Additionally the applications that are visible on the home site can also serve as example. Their source code is available on the download site.

How does this framework work?

A question that is answered with a manual and some examples. Have a look at the guide for the core library, the guide for the common project, the tutorial project or at the online api documentation.
There is also a forum online: Byte-Welt (in former times german, now english)

What do I do if I find a bug?

Write a message in the forum Byte-Welt (there once was a bugtracker, but the forum proved to be better fitting to my style of working).
Never hesitate to fill in a bug report. If it is a bug in the framework, I will fix it as soon as possible. Many bugs are fixed within hours (or days), the version in the repository is always ready for a release. If it is a misunderstanding in your code, then you will be happy about any help someone more experienced with the framework can provide. And no question is too dumb to be asked.

How is backwards compatibility handled?

There is only a limited guarantee for backwards compatibility. The more public interfaces are changed seldomly, but the innards of the framework may experience more dramatic changes.
The normal rules for incompatible API changes are:

• If it is required for a bugfix: do it immediately, always.
• If it is inner/hidden API: do it immediately.
• If it is more public API: mark the API as deprecated but keep supporting it for a while. If API is deprecated in version n, then it may be removed in version n+1.

Is it me, or is this framework really hard to understand?

Well... it is not you. There are three factors contributing to the complexity:

• Man power: there is only one fulltime developer on this project (that would be me). And I just don't have the time to test everything, so I prefer to keep old code that has proven to be correct. Sometimes this leads to a layer around a layer around a layer... you get the picture.
• Backwards compatibility: Nowadays the framework is used by more than one project. Even if some design proves to be questionable, it is hard to repair it without breaking old code.
• Flexibility: The framework offers a lot of flexibility, I would even go so far to say that it is one (if not the) of the most flexible docking frameworks for Java. But flexibility always means more interfaces, more extension points and more properties. And that just sums up.

How to write a small application?

Applications are best written by using the Common API. For this the libraries "docking-frames-common.jar" and "docking-frames-core.jar" have to be included in the classpath. Common hides a lot complexety from the underlying Core API, and adds a nice set of additional features. Clients should whenever possible use the Common API!

Have a look at the code, and later on the explanation of the code.

package test;

import java.awt.Color;

import javax.swing.JFrame;
import javax.swing.JMenuBar;
import javax.swing.JPanel;

import bibliothek.gui.dock.common.*;
import bibliothek.gui.dock.common.menu.SingleCDockableListMenuPiece;
import bibliothek.gui.dock.facile.menu.RootMenuPiece;

public class Dock {
        public static void main( String[] args ){
                JFrame frame = new JFrame( "Demo" );
                CControl control = new CControl( frame );
                
                frame.add( control.getContentArea() );
                
                CGrid grid = new CGrid( control );
                grid.add( 0, 0, 1, 1, createDockable( "Red", Color.RED ) );
                grid.add( 0, 1, 1, 1, createDockable( "Green", Color.GREEN ) );
                grid.add( 1, 0, 1, 1, createDockable( "Blue", Color.BLUE ) );
                grid.add( 1, 1, 1, 1, createDockable( "Yellow", Color.YELLOW ) );
                control.getContentArea().deploy( grid );
                
                SingleCDockable black = createDockable( "Black", Color.BLACK );
                control.addDockable( black );
                black.setLocation( CLocation.base().minimalNorth() );
                black.setVisible( true );
                
                RootMenuPiece menu = new RootMenuPiece( "Colors", false );
                menu.add( new SingleCDockableListMenuPiece( control ));
                JMenuBar menuBar = new JMenuBar();
                menuBar.add( menu.getMenu() );
                frame.setJMenuBar( menuBar );
                
                frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
                frame.setBounds( 20, 20, 400, 400 );
                frame.setVisible( true );
        }
        
        public static SingleCDockable createDockable( String title, Color color ) {
                JPanel panel = new JPanel();
                panel.setOpaque( true );
                panel.setBackground( color );
                DefaultSingleCDockable dockable = new DefaultSingleCDockable( title, title, panel );
                dockable.setCloseable( true );
                return dockable;
        }
}

Now lets explain the code:

JFrame frame = new JFrame( "Demo" );
CControl control = new CControl( frame );

frame.add( control.getContentArea() );

Here a controller and a content area are created. The content area is a JComponent which has several "Dockables" as children. The controller manages all the elements of DockingFrames.

CGrid grid = new CGrid( control );
grid.add( 0, 0, 1, 1, createDockable( "Red", Color.RED ) );
grid.add( 0, 1, 1, 1, createDockable( "Green", Color.GREEN ) );
grid.add( 1, 0, 1, 1, createDockable( "Blue", Color.BLUE ) );
grid.add( 1, 1, 1, 1, createDockable( "Yellow", Color.YELLOW ) );
control.getContentArea().deploy( grid );

Here some "Dockables" are created and put into a grid. A grid just describes a layout, it does not become part of the dock-tree. Finally the content of the grid is used to put the "Dockables" onto the content area.

SingleCDockable black = createDockable( "Black", Color.BLACK );
control.addDockable( black );
black.setLocation( CLocation.base().minimalNorth() );
black.setVisible( true );

It is possible to add single "Dockables" at any time. Each "Dockable" must be registered at a controller. The location is optional, a default location would be used if the location were not set. Eventually the "Dockable" is made visible.

RootMenuPiece menu = new RootMenuPiece( "Colors", false );
menu.add( new SingleCDockableListMenuPiece( control ));
JMenuBar menuBar = new JMenuBar();
menuBar.add( menu.getMenu() );
frame.setJMenuBar( menuBar );

The common-project contains some menus. These menus can be combined in a tree of "MenuPieces". Here only one piece is used, the "SingleCDockableListMenuPiece". It shows a "JCheckBoxMenuItem" for each "SingleCDockable" that is in the realm of the controller. With this menu, each "Dockable" can be made visible or invisible.

How to write a small application with the Core API?

The Core API offers all the features needed to drag and drop Dockables. But compared to the Common API it is much more complex. However, for a really small application you don't need much code:

Have a look at the code, and later on the explanation of the code.

package test;

import java.awt.Color;

import javax.swing.JFrame;
import javax.swing.JPanel;

import bibliothek.gui.DockFrontend;
import bibliothek.gui.Dockable;
import bibliothek.gui.dock.DefaultDockable;
import bibliothek.gui.dock.SplitDockStation;
import bibliothek.gui.dock.station.split.SplitDockGrid;

public class Dock {
        public static void main( String[] args ){
                JFrame frame = new JFrame( "Demo" );
                DockFrontend frontend = new DockFrontend( frame );
                SplitDockStation station = new SplitDockStation();
                
                frame.add( station.getComponent() );
                frontend.addRoot( station, "station" );
                
                SplitDockGrid grid = new SplitDockGrid();
                grid.addDockable( 0, 0, 1, 1, createDockable( "Red", Color.RED ) );
                grid.addDockable( 0, 1, 1, 1, createDockable( "Green", Color.GREEN ) );
                grid.addDockable( 1, 0, 1, 1, createDockable( "Blue", Color.BLUE ) );
                grid.addDockable( 1, 1, 1, 1, createDockable( "Yellow", Color.YELLOW ) );
                station.dropTree( grid.toTree() );
                
                frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
                frame.setBounds( 20, 20, 400, 400 );
                frame.setVisible( true );
        }
        
        public static Dockable createDockable( String title, Color color ){
                JPanel panel = new JPanel();
                panel.setOpaque( true );
                panel.setBackground( color );
                return new DefaultDockable( panel, title );
        }
}

Now lets explain the code:

DockFrontend frontend = new DockFrontend( frame );
SplitDockStation station = new SplitDockStation();

Here a frontend is created. A frontend hides the more complex operations from the developer.
Also a station is created. A station is a container for visible panels.

frontend.addRoot( station, "station" );

Connect the root-station with the frontend.

SplitDockGrid grid = new SplitDockGrid();
grid.addDockable( 0, 0, 1, 1, createDockable( "Red", Color.RED ) );
grid.addDockable( 0, 1, 1, 1, createDockable( "Green", Color.GREEN ) );
grid.addDockable( 1, 0, 1, 1, createDockable( "Blue", Color.BLUE ) );
grid.addDockable( 1, 1, 1, 1, createDockable( "Yellow", Color.YELLOW ) );
station.dropTree( grid.toTree() );

Here we use a helper-class. First we create a layout containing four panels, then we transform the layout in a form which can be understood by the station. The panels could be dropped directly without the grid, but the result would not look so nice.

JPanel panel = new JPanel();
panel.setOpaque( true );
panel.setBackground( color );
return new DefaultDockable( panel, title );

Every panel that we want to show, must be wrapped into a "Dockable". The "DefaultDockable", which we use here, can be compared to a "JInternalFrame": it has a content-pane where we can add our stuff (or we can go directly through the constructor).