[API Review] RT-27887: introduce a node to embed Swing into JavaFX

[Anton V. Tarasov]

Hi All,

Based on the feedback, I'm modifying the threading contract for the 
set/get methods.
Only Swing thread is allowed for them, where JComponent is to be 
accessed/modified.

I'm not adding a contentProperty. My reasoning is as follows:

- AFAIK, all fx properties are limited to JavaFX App thread, I'm 
hesitating to break it...
- there's not a real need in listening to this property, it's more like 
ones set and never changed
- at worst, the property can be added lately, without modification to 
the set/get methods API

Here's the updated javadoc:

     /**
      * Attaches a {@code JComponent} instance to display in this {@code 
SwingNode}.
      * The method must be called on the Swing thread, otherwise it will 
throw
      * {@code IllegalStateException}.
      *
      * @param content a component to display in this {@code SwingNode}
      *
      * @throws IllegalStateException if this method is called on a thread
      *               other than the Swing thread
      * @see java.awt.EventQueue#isDispatchThread()
      */
     public void setContent(final JComponent content);


    /**
      * Returns the {@code JComponent} instance attached to this {@code 
SwingNode}.
      * The method must be called on the Swing thread, otherwise it will 
throw
      * {@code IllegalStateException}.
      *
      * @throws IllegalStateException if this method is called on a thread
      *               other than the Swing thread
      * @see java.awt.EventQueue#isDispatchThread()
      *
      * @return the {@code JComponent} instance attached to this {@code 
SwingNode}
      */
     public JComponent getContent();


Thanks,
Anton.


On 1/24/13 10:49 PM, Anton V. Tarasov wrote:
> Hi All,
>
> Please, review a request to add a new SwingNode class:
>
> http://javafx-jira.kenai.com/browse/RT-27887
>
> /**
>  * This class is used to embed a Swing content into a JavaFX application.
>  * The content to be displayed is specified with the {@link 
> #setContent} method
>  * that accepts an instance of Swing {@code JComponent}. The hierarchy 
> of components
>  * contained in the {@code JComponent} instance should not contain any 
> heavyweight
>  * components, otherwise {@code SwingNode} may fail to paint it. The 
> content gets
>  * repainted automatically. All the input and focus events are 
> forwarded to the
>  * {@code JComponent} instance transparently to the developer.
>  * <p>
>  * Here is a typical pattern which demonstrates how {@code SwingNode} 
> can be used:
>  * <pre>
>  *     public class SwingFx extends Application {
>  *
>  *         private SwingNode swingNode;
>  *
>  * &#064;Override
>  *         public void start(Stage stage) {
>  *             swingNode = new SwingNode();
>  *
>  *             createAndSetSwingContent();
>  *
>  *             StackPane pane = new StackPane();
>  *             pane.getChildren().add(swingNode);
>  *
>  *             stage.setScene(new Scene(pane, 100, 50));
>  *             stage.show();
>  *         }
>  *
>  *         private void createAndSetSwingContent() {
>  *             SwingUtilities.invokeLater(new Runnable() {
>  * &#064;Override
>  *                 public void run() {
>  *                     swingNode.setContent(new JButton("Click me!"));
>  *                 }
>  *             });
>  *         }
>  *     }
>  * </pre>
>  */
> public class SwingNode extends Node {
>    /**
>      * Constructs a new instance of {@code SwingNode}.
>      */
>     public SwingNode();
>
>     /**
>      * Attaches a {@code JComponent} instance to display in this 
> {@code SwingNode}.
>      * The method can be called either on the event dispatch thread or 
> the JavaFX
>      * application thread.
>      *
>      * @param content a component to display in this {@code SwingNode}
>      *
>      * @see java.awt.EventQueue#isDispatchThread()
>      * @see javafx.application.Platform#isFxApplicationThread()
>      */
>     public void setContent(final JComponent content);
>
>     /**
>      * Returns the {@code JComponent} instance attached to this {@code 
> SwingNode}.
>      *
>      * @return the {@code JComponent} instance attached to this {@code 
> SwingNode}
>      */
>     public JComponent getContent();
> }
>
> Additional question is about disposing. When SwingNode is removed from 
> a Scene its underlying
> resources (on the AWT toolkit side) should be released. An option is 
> to add a "dispose" method to
> the node and leave it to a user's discretion when to call it. However, 
> having this managed
> automatically would be preferable. For that, a node should be able to 
> be notified when it is no
> longer a part of a rendering process. This is an issue and it is 
> tracked separately as RT-129.
>
> Thanks,
> Anton.
>
>