The Java Swing API is a nearly exhaustive collection of user interface widgets that can be used to build a user interface around a Java 3D application. There are some real challenges to mixing Swing and Java 3D components. This is largely because Swing components are lightweight whereas the Java 3D Canvas3D component is heavyweight.
The difference between lightweight and heavyweight components is a bit obscure. Simply stated, heavyweight components reference their own native screen resource called a peer. A lightweight component has no native peer and therefore temporarily uses the resources of a nearby native peer.
In general, lightweight UI components have many advantages including having a smaller resource footprint and also the ability to maintain a consistent look and feel across platforms. The downside is that some components do not have lightweight versions; therefore, it becomes necessary to mix lightweight and heavyweight. This is the exact situation that happens when we want to use the heavyweight Canvas3D object (which, as you know, is necessary to view our 3D scene) in conjunction with Swing components. There is no lightweight version of the Canvas3D object.
We should note that several of the Swing components are indeed heavyweight by design. In particular, the top-level components JWindow, JFrame, JApplet, and JDialog are all heavyweight. These components can be mixed with a Canvas3D object without concern. All AWT components are heavyweight as well.
Three main problems occur when mixing heavyweight and lightweight components:
Mouse events for lightweight components filter up to the heavyweight parent, whereas mouse events for heavyweight components do not.
Heavyweight components always appear on top of lightweight components regardless of the z order in which they are rendered.
Lightweight components can have transparent pixels, whereas heavyweight components do not.
This section focuses on the second and third problems, which are of the most concern in Java 3D. The first problem does not interfere with the working of Java 3D in general, and thus won't be discussed further.
Returning to the second and third problems, we can see issues with the display of the Canvas3D. A partial solution to these display problems can be solved by avoiding certain situations or, alternatively, setting a flag to override lightweight functioning of the component.
First and foremost, avoid mixing lightweight and heavyweight components. This can be accomplished by keeping the heavyweight components in an area of the screen where lightweight components are not expected to overlap.
Also in terms of mixing components, certain lightweight components should never have a heavyweight component added to them. The two most common examples of this are adding a Canvas3D to a JInternalFrame or JScrollPane.
The same problems can occur when using pop-up components such as JComboBox or JPopupMenu. In this case, Java determines what the ideal weight of these objects should be in the context of the application. This decision is dependent on whether a property called LightWeightPopupEnabled is set to true or false. For example, if a JPopupMenu is activated, it can be heavyweight if the component does not fit entirely in its container, mediumweight if the pop-up fits within the top-level component but the lightweightPopupEnabled property is set to false, or truly lightweight if the pop-up fits within the top-level component but lightweightPopupEnabled is set to true (the default).
Therefore, you can set the LightWeightPopupEnabled property to false to ensure that the component is heavyweight. There are two methods for setting this property—one global (applies to all pop-ups) and the other more restricted (on a pop-up by pop-up basis).
The global method is
public static void setDefaultLightweightPopupEnabled(boolean)
To change the property for an individual pop-up component, use the following:
public void setLightweightPopupEnabled(Boolean)
The BadMix.java example in Listing 12.14 illustrates the preceding two approaches to mixing heavy- and lightweight components.