= pTolemy3D - How to start =

[[PageOutline(2-3,,inline)]]
----

== Introduction ==


The aim of this document is to introduce how to initialize use pTolemy3D Core and to describe the basis feature you'll need to learn to know how things works.

As example, pTolemy3D Viewer will be integrated inside a basic application (a frame) and inside an applet.


The pTolemy3D package has been described in PtolemyOverview document.


== Integration in an Application ==


pTolemy3D is initialized from a set of configuration parameters related to map server, initiale position, plugins, ...

The list of parameters is not introduced and explained here, for that look at the document: XXX.
Ptolemy3D Initialization

{{{

/*
 * Ptolemy3D instanciation
 */
final Ptolemy3D ptolemy = new Ptolemy3D();

/*
 * Ptolemy3D initialization
 */
//Build document from the XML configuration file
//If null is passed, parameters will be search inside the applet tag.
Element config = Ptolemy3DConfiguration.buildXMLDocument(xmlFile);
ptolemy.init(config);
}}}

 

 

Ptolemy 3d uses JOGL OpenGL Binding. For flexibility, the user can choose between a GLCanvas (AWT) or a GLJPanel (Swing/Lightweight) component for the Ptolemy3D rendering area.
Ptolemy3D Rendering Area


{{{
//Creating the rendering area for Ptolemy rendering
final GLCanvas component3d = new GLCanvas();
//final GLJPanel component3d = new GLJPanel();

//Register Ptolemy3D rendering events
component3d.addGLEventListener(ptolemy.events);

component3d.setSize(new Dimension(width, height));
}}}

 

Finally, you can integrate the rendering area component as wanted inside any application or applet.

The next code integrate the rendering area created above inside an application (the full source code is available in: org.ptolemy3d.example.SimpleFrame).
Integration inside an application

{{{

/*
 * Ptolemy3D Example Application
 */
//Creating the Frame and adding the Ptolemy3D rendering area
final JFrame frame = new JFrame("Ptolemy3D Example - Simple Frame");
frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
frame.setLayout(new BorderLayout());
frame.add(component3d, BorderLayout.CENTER);
frame.pack();

//Register listeners
this.addMouseListener(new MouseAdapter() {
    public void mouseEntered(MouseEvent e) {
        requestFocus();
    }
});
this.addWindowListener(new WindowAdapter( ){
    public void windowClosing(WindowEvent e) {
        getInputContext().removeNotify(component3d);
       
        //Ptolemy3D destruction
        ptolemy3d.destroy();

        frame.remove(component);
        frame.dispose();
    }
});

/*
 * Show the frame and start Ptolemy3D Rendering
 */
frame.setVisible(true);
}}}


 

== Integration in an Applet ==


An interesting way to use Ptolemy3D is inside an applet. The initialization is similar and the example below show how to integrate Ptolemy3D within the applet life time.

 (the full source code is available in: org.ptolemy3d.example.SimpleApplet).

 

Here is how to integration pTolemy3D inside any applet:



{{{
private Ptolemy3D ptolemy3d;
private GLCanvas component3d;
private JSObject jsObject;

public void init()
{
    /*
     * Javascript link with Ptolemy3D
     */
    if(jsObject == null) {
        JSObject obj;
        try {
            obj = JSObject.getWindow(this);
        } catch(RuntimeException e) {
            obj = null;
        }
        this.jsObject = obj;
    }

    /*
     * Ptolemy3D standard initialization
     */
    if(ptolemy3d == null) {
        ptolemy3d = new Ptolemy3D();
        ptolemy3d.javascript = this;  //this implements Ptolemy3DJavascript interface
        ptolemy3d.init(null);

        this.component3d = new GLCanvas();
        this.component3d.addGLEventListener(ptolemy3d.events);
        this.component3d.setSize(getSize());

        this.setLayout(new BorderLayout());
        this.add(this.component3d, BorderLayout.CENTER);
        this.addMouseListener(new MouseAdapter() {
            public void mouseEntered(MouseEvent e) {
                requestFocus();
            }
        });
    }
}

public void start()
{
    if(ptolemy3d == null) {
        init();
    }
   
    requestFocus();
}

public void stop()
{
    getInputContext().removeNotify(component3d);

    /*
     * Ptolemy3D destruction
     */
    ptolemy3d.destroy();
    ptolemy3d = null;

    //Remove 3D component
    removeAll();
    component3d = null;
}

@Override
public void destroy()
{

}

/* Ptolemy3DJavascript interface */

public Applet getApplet()
{
    return this;
}

public JSObject getJSObject()
{
    return jsObject;
}

}}}

 

== More documentation ==

We've seen how to initialize and integrate pTolemy3D in every kind of java application.

pTolemy3D object (org.ptolemy3d.Ptolemy3D), created during the initialization steps, is the core object for accessing every datas of Ptolemy3D. The documentation for that is located in the javadoc at:

http://www.pTolemy3D.org/javadocs