Java Doc for TabbedContainer.java in  » IDE-Netbeans » library » org » netbeans » swing » tabcontrol » Java Source Code / Java DocumentationJava Source Code and Java Documentation

The first difference from a JTabbedPane is that it is entirely model driven - the tab contents are in a data model owned by the displayer. It is not strictly necessary for the contained components to even be installed in the AWT hierarchy when not displayed.

Other differences are more flexibility in the way tabs are displayed by completely separating the implementation and UI for that from that of displaying the contents.

Other interesting aspects are the ability of TabDataModel to deliver complex, granular events in a single pass with no information loss. Generally, great effort has been gone to to conflate nothing - that is, adding a component does not equal selecting it does not equal changing focus, et. cetera, leaving these decisions more in the hands of the user of the control.

It is possible to implement a subclass which provides the API of JTabbedPane, making it a drop-in replacement.

There are several UI styles a TabbedContainer can have. The type is passed as an argument to the constructor (support for changing these on the fly may be added in the future, but such a change is a very heavyweight operation, and is only desirable to enable use of this component in its various permutations inside GUI designers). The following styles are supported:

• TYPE_VIEW - These are tabs such as the Explorer window has in NetBeans - all tabs are always displayed, with the available space equally divided between them.
• TYPE_EDITOR - Scrolling tabs, coupled with control buttons and mouse wheel support for scrolling the visible tabs, and a popup which displays a list of tabs.
• TYPE_SLIDING - Tabs which are displayed as buttons, and may provide a fade or sliding effect when displayed. For this style, a second click on the selected tab will hide the selected tab (setting the selection model's selected index to -1).

Customizing the appearance of tabs

Managing user events on tabs

Indication of focus and the "activated" state

1. Use an AWT even listener to track mouse clicks, and when the mouse is clicked,
   • Find the ancestor that is a tabbed container (if any)
   • Set the activated state appropriately on it and the previously active container
   • Ensure that keyboard focus moves into that container
2. Block ctrl-tab style keyboard based focus traversal out of tabbed containers
3. Provide keyboard actions, with menu items, which will change to a different container, activating it

This is the least scalable of the available UI types, and is intended primarily for use with a small, fixed set of tabs.

• CONTENT_POLICY_ADD_ALL - All components in the data model are automatically added to the container, and whenever the model changes, components are added and removed as need be.

Will first search UIManager for a matching UI class.

This is the least scalable of the available UI types, and is intended primarily for use with a small, fixed set of tabs. By default, the position of the tab displayer will be determined based on the proximity of the container to the edges of its parent window. This can be turned off by setting the client property PROP_MANAGE_TAB_POSITION to Boolean.FALSE.

1. There are methods on TabActionEvent to find the index of the tab the event was performed on, and if present, retrieve the mouse event that triggered it, for clients that wish to provide different handling for different mouse buttons
2. TabActionEvents can be consumed. If a listener consumes the event, the UI will take no action - the selection will not be changed, the tab will not be closed. Consuming the event means taking responsibility for doing whatever would normally happen automatically. This is useful for, for example, showing a dialog and possibly aborting closing a tab if it contains unsaved data, for instance.

• CONTENT_POLICY_ADD_ALL - All components in the data model are automatically added to the container, and whenever the model changes, components are added and removed as need be. This is less scalable, but absolutely reliable
• CONTENT_POLICY_ADD_ON_FIRST_USE - Components are not added to the container until the first time they are used, and then they remain in the AWT hierarchy until their TabData elements are removed from the model. This is more scalable, and probably has some startup time benefits
• CONTENT_POLICY_ADD_ONLY_SELECTED - The only component that will ever be in the AWT hierarchy is the one that is being displayed. This is safest in the case that heavyweight AWT components may be used

NetBeans uses an AWTEventListener to track mouse clicks, and allows components to become activated only via a mouse click or via a keyboard action or menu item which activates the component. This approach is far more robust and is the recommended usage pattern.

For use cases where a single component is to be displayed for more than one tab, just reconfigured when the selection changes, simply supply a ComponentConverter.Fixed with the component that should be used for all tabs.

Will first search UIManager for a matching UI class. If non-null (by default it is set in the core/swing/plaf library), it will compare the found class name with the current UI. If they are a match, it will call TabbedContainerUI.shouldReplaceUI() to decide whether to actually do anything or not (in most cases it would just replace an instance of DefaultTabbedContainerUI with another one; but this call allows DefaultTabbedContainerUI.uichange() to update the tab displayer as needed).

If no UIManager UI class is defined, this method will silently use an instance of DefaultTabbedContainerUI.