Toolbar Extension (since version 1.1.1p8)
In version 1.1.1p8 the Toolbar Extension has been included into the framework, you will find new jar-files and folders in the big zip file that you can download from the webpage. This extension was written by Hervé Guillaume and myself. We started working on the extension in the late summer of 2011, and Hervé has been using and testing it since early 2012.
What are the features?
Toolbars, obviously :o)
In general a toolbar is a set of buttons. The user may be able to move around the toolbar, or even add/remove buttons from it. The extension makes use of the drag and drop mechanism offered by DockingFrames, and allows to build very flexibel toolbars.
[ul]
[li] Each “button” is a Dockable. Which means each button can be moved around individually.
[/li][li] Each “toolbar” is a list of buttons. Toolbars are Dockables as well.
[/li][li] Several toolbars are combined to a “toolbar group”, which is yet another Dockable.
[/li][li] Several groups are shown by one “toolbar container”.
[/li][li] Like in Core and Common, there are many configurations that can be modified.
[/li][/ul]
How to use?
First you need to include the jar files “docking-frames-ext-toolbar.jar” and “docking-frames-ext-toolbar-common.jar” into the classpath of your application. The framework will automatically install the extension, and the extension will change some of the default configurations.
Second you start the tutorial application “docking-frames-demo-tutorial.jar”, you find new tutorials in “Basics/Core/Toolbar” and “Basics/Common/Toolbar”. These tutorials should explain everything you need. If not, ask in this forum for help.
What are the dangers?
The extension is not completely finished. There are some features missing, e.g. there is no support for perspectives. Missing features will be added over time, asking for them in the forum may drastically increase the likelihood for a feature to appear soon.
Also there are still some bugs present. Reporting them in the forum will drastically decrease their lifetime.
Changes
To support the extension, changes have been made to the Core and Common project. Most of these changes should not affect existing applications, but knowing about them may help you using the new features. This list does only include changes that were applied to 1.1.1p8.
** - API: New Inserter can override drop operations before and after they are created**
The interface “Inserter” adds an additional layer in the algorithm that calculates the target of a drag and drop operation. The inserter is informed before and after a target is chosen, in both cases the inserter can exchange or invalidate the target. Inserters can either be set directly by calling DockRelocator.setInserter, or as extension by using the extension point “DefaultDockRelocator.INSERTER_EXTENSION”.
** - API: A lot more configuration options for the ScreenDockStation, these configurations are done by the ScreenDockWindowConfiguration.**
The windows that show floating Dockables can now be configured by a “WindowConfiguration”. A WindowConfiguration is created by the factory “ScreenDockWindowConfiguration” which can be set with the property key “ScreenDockStation.WINDOW_CONFIGURATION”. The WindowConfiguration itself offers settings like transparency, whether the window can be resized, or whether the user can move the window by grabbing the title of a Dockable.
** ! API: PaintableComponent uses now a transparency enumeration instead of two booleans **
Transparency really has 3 different states: transparent, not transparent, and semi transparent. Previously these 3 states were represented by 2 booleans, but that of course leaves one invalid combination of the booleans. The booleans have now been replaced by the enumration “Transparency”.
** - API: AbstractDockTitle has been divided into two classes, there is no need to change code in the subclasses of AbstractDockTitle**
AbstractDockTitle is now responsible for showing buttons for DockActions, AbstractMultiDockTitle completely ignores any actions.
** ! API: DockActions now support icons that are shown if the mouse hovers of the action, or if the mouse is pressed. Clients just using the DockAction interface should compile without changes, but subclasses of DockAction will require updates.**
With help of the new enumeration class “ActionContentModifier”, StandardDockActions can now offer many icons for different purposes. For example an action can show a different icon when the mouse hovers over it. Additional “set/getIcon” methods have been added to the DockActions to allow clients setting the new icons.
** - API: The window that shows up when moving a dockable (DefaultDockRelocator.ImageWindow) is now transparent**
And the “MovingImage”, the class providing the content for the window, is informed on whether transparency was successfully set or not.
** ! API: MovingImage now can set an offset and is informed if the underlying window is transparent**
The offset allows the image to decide on its own where to appear. For example it could appear at the top side of the mouse.
** ! API: NoTitleDisplayer gets replaced by NoTitleBarDisplayer. The new displayer extends BasicDockableDisplayer (now all displayer are derived from this class) and is able to show a DockTitle if asked to do so. **
This also means, that all DockableDisplayers are now subclasses of BasicDockableDisplayer. NoTitleDisplayer was always a special case, a DockableDisplayer that did have a bit strange behavior, and that needed special care when configuring. All these nuisances are gone now.
** - Bugfix: Resizing a ScreenDockWindow to a size smaller than its acceptable minimum will no longer move the window. **
Changes the behavior from something that most people considered to be very annoying to something more intuitive.
** - API: The ScreenDropSizeStrategy allows to influence the size a dropped Dockable on a ScreenDockStation gets **
It is not entirely clear: when dropping a Dockable onto the ScreenDockStation, it could have any size it wants. Should that be its preferred size, or the size it had on its old parent? The “ScreenDropSizeStrategy” allows clients to decide this question, this strategy can be installed using the property key “ScreenDockStation.DROP_SIZE_STRATEGY”.
** ! API: ExtendedModeEnablement now also decides which hints (buttons) are visible for the user**
Does not really affect clients at all. The standard DockingFrames offers four modes: normalized, minimized, maximized and externalized. The Toolbar Extension adds a new mode “toolbar”. Now toolbars have titles, but there is no need to show buttons like “externalize” in this title. The toolbar-mode needed an ability to suppress actions that are not needed, and hence ExtendedModeEnablement was updated.
** ! API: StackDockComponent has now a custom listener instead of the generic ChangeListener**
Once again a feature that will not affect clients. The new listener is just able to receive more events needed to find out whether a tab is actually shown for some Dockable or not.