Creating Ensemble Samples

Ensemble is a demo program that allows you to show off running code, source code, and documentation all in one place. It was originally written for use by the JavaFX team at Oracle, but JFXtras has adapted a version to use in demonstrating the controls in our libraries.

Adding a new demo to Ensemble is as easy as creating a new .java file in one of the ensemble.samples.* packages that exist in the Ensemble source. The packages below the ensemble.samples package will be transformed into the tree structure shown by Ensemble. The new file should contain a class that extends the Sample class and whose name ends with Sample. For example:

package ensemble.samples.gauges.radial;

public class RadialGaugeSample extends Sample {
    // ...
}

Don't forget to override the Sample class's play and stop methods if you are using animation in your samples. Start the animation in the play method, stop it again in the stop method.

    @Override
    public void play() {
        myTimeline.play();
    }

    @Override
    public void stop() {
        mTimeline.stop();
    }

The next time the Ensemble project is cleaned and built, one of the steps that will be run is to build the search index. This creates a search index of all the samples and documentation, but also creates a file called samplesAll.txt. This latter file is used to create the list of samples that Ensemble will show to the user.

Each sample can also provide an icon that Ensemble will use to represent the sample to the user. The sample's icon is set in one of two ways. First, you can create a .png file having the same name as the sample and place it into the sample's package along side its .java file. If you use Adobe Photoshop, there is a file called "ensemble icon template.psd" in the artSrc directory of the jfxtras-ensemble repository. This .psd file, donated by Jasper Potts, can and should be used to easily create Ensemble-style icons for you sample.

The alternative to creating static .png files as icons is to create a public static createIconContent() method in your Sample class. This method should return a Node and will be called using reflection if it exists in your class and the .png file mentioned previously doesn't exist. The advantage of using a Node as the sample's icon is that it can include animation. In this case, you should only play the animation when the mouse is hovering over the Node returned by your method. This is accomplished by manually attaching listeners to your root node's onMouseEntered and onMouseExited.

public static Node createIconContent() {
    // Create myNode1 and myNode2 (or whatever) as content for this icon...
    javafx.scene.Group g = new javafx.scene.Group(myNode1, myNode2);

    g.setOnMouseEntered(new EventHandler<javafx.scene.input.MouseEvent>() {
        @Override public void handle(javafx.scene.input.MouseEvent e) {
            tl.play();
        }
    });
    g.setOnMouseExited(new EventHandler<javafx.scene.input.MouseEvent>() {
        @Override public void handle(javafx.scene.input.MouseEvent e) {
            tl.pause();
        }
    });
    return g;
}

Documenting Your Samples

Ensemble will automatically pull documentation from your class-level javadoc comments. Take the following comment:

/**
 * CalendarTextField and CalendarPicker.
 *
 * @see jfxtras.labs.scene.control.CalendarTextField
 */
public class CalendarTextFieldSample extends Sample {
    // ...
}

Ensemble will pull out the text of the comment and use it as a description of the sample. This description appears to the right of the sample when it is run. Any @see parameters that appear in the comment block will be listed as See Also lines underneath the description and will appear as hyperlinks to Ensemble's built-in copy of the JFXtras javadocs (when this is working!).