Getting Started

Here you will find both basic and advanced tutorials to help you get started using Piccolo2D.  All tutorials provide examples in both Java and C#.  This section assumes you have read Piccolo2D Patterns and have a basic understanding of the concepts presented there.

Piccolo2D.Java - Out of the Box

This tutorial will help you figure out where to begin.  It will guide you from downloading Piccolo2D to writing and compiling your first zoomable user interface.

1. Get the Pre-Requisites

In order to write your first Piccolo2D.Java application, you will need to make sure that you have the following:

Java 2 Platform, Standard Edition (J2SE)
To run any Piccolo2D.Java code, you must have the Java 2 Platform  installed on your machine. If you do not have the Java 2 Platform, you should first download the J2SE installer and install the Java 2 Platform.
Eclipse IDE
This tutorial assumes that you are using Eclipse as your development environment.  Eclipse is not required to write Piccolo2D.Java applications, but we do recommend using it. Once you have installed the Java 2 Platform, you can download and install eclipse.
Piccolo2D classes
Of course, you will need Piccolo2D.Java. You can download the Jar files or the full source code from the download page.

2. Setting up the Environment

These steps will help you setup the Eclipse environment to begin Piccolo2D.Java development.

Add Piccolo2D to Eclipse

  1. Open the Eclipse IDE.
  2. Choose File > New Project, and create a new Java project named "piccolo2d".
  3. Locate the file piccolo2d-xxx.zip, which you downloaded in step 1.  Extract the zipped package using WinZip or another compression utility.
  4. Renamed the extracted Piccolo2D-xxx folder to the name (my choice was piccolo2d) of the eclipse project that you created in step a.
  5. Locate the Eclipse workspace folder. This folder is located inside the folder that holds your Eclipse installation.
  6. Drag the renamed piccolo2d folder into the workspace folder, replacing the existing piccolo2d folder in the workspace.
  7. Last of all go into Eclipse and right-click on the piccolo2d project and choose "Refresh" from the popup menu.
  8. Piccolo2D's classes should now be visible in eclipse.

3. Building Your First ZUI

These steps will guide you through writing your first zoomable user interface with Piccolo2D.Java.

3.1. Create a new Java project in Eclipse.

Here you will create a new Eclipse java project.

  1. In Eclipse choose File > New Project and create another "Java Project". This time name the project "Hello World".

3.2. Add References to Piccolo2D

These steps will add references to the Piccolo2D project so that you can use Piccolo2D's classes in your own project.

  1. Right click on your new "Hello World" project and choose "Properties".
  2. In the properties panel click on the "Java Build Path" list item on the left.
  3. Now click on the "Projects" tab and choose the "Add..." button. Check to add the "piccolo2d" project that you created earlier.
  4. Now your "Hello World" project is setup to use classes from the "piccolo2d" project.

3.3. Subclass JFrame

Next we will subclass the standard Swing class JFrame.

  1. Select your "Hello World" project and then choose File > New > Class.
  2. Name the new class "HelloWorldExample".
  3. Choose the Superclass javax.swing.JFrame.
  4. Check the box labeled "public static void main(String[] args)" so that a main method will be created for your class.
  5. Click the Finish button to create you new class.

3.4. Write the Code

Now we will write our first Piccolo2D code.

  1. At the top of the screen add the following import statements so that we can use the PCanvas and PText classes. 
    import javax.swing.JFrame;

import edu.umd.cs.piccolo.PCanvas;
import edu.umd.cs.piccolo.nodes.PText;
  2. The constructor is used to initialize and wire up piccolo2d, so create one like this: 
            private HelloWorldExample() {
                final PCanvas canvas = new PCanvas();
                final PText text = new PText("Hello World");
                canvas.getLayer().addChild(text);
                add(canvas);

                setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
                setSize(600, 400);
                setVisible(true);
        }
    Last of all override main method so that a new instance of your "HelloWorldExample" class gets created by main. The final code should look like this: 
    import javax.swing.JFrame;

import edu.umd.cs.piccolo.PCanvas;
import edu.umd.cs.piccolo.nodes.PText;

public class HelloWorldExample extends JFrame {
        
        private HelloWorldExample() {
                final PCanvas canvas = new PCanvas();
                final PText text = new PText("Hello World");
                canvas.getLayer().addChild(text);
                add(canvas);

                setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
                setSize(600, 400);
                setVisible(true);
        }

        public static void main(String[] args) {
                new HelloWorldExample();
        }
}
    That's it! You've just written your first zooming application. The first line creates a new PText node and initializes it to the string "Hello World". And, the second line adds the new node to the main layer of the canvas.  Zooming and panning are there for free.

3.5. Run the Code

Now let's see Piccolo2D in Action

  1. Right-click on your "HelloWorldExample" class and choose Run As > Java Application
  2. You should see the text "Hello World"
  3. Click anywhere in the window with the left mouse button and drag to pan the camera around.
  4. Click anywhere in the window with the right mouse button and drag to the right to zoom in on the point.  Drag to the left to zoom out.

The reason this works is because the zoom and pan event handlers are installed by default.  See the Defining User Interaction tutorial for more details.