A Roadmap to…

Introduction
2D Chart Types
3D Chart Types
Review PFJ Documentation
System Requirements
Check our Web Site for Latest Version
Review Chart Editor Application
Review PFJ's Loading and Saving Features
Review Chart Editor Applet
PFJ as a JavaBean in Visual Cafe
PFJ as a JavaBean in JBuilder
Design a Chart Using HTML
Using Your Data in a Chart
Conclusion
Properties Index
Methods Index

Introduction

Three D Graphics has provided charting technology to the leading members of the software industry for over a decade. The "Perspective Look" is in use in over 5 million seats worldwide. Now you can bring this power and flexibility to your own Java development environment.

Perspective for Java is a Java Class Library, JavaBean and a collection of applets for creating extraordinary charts from data in any Java environment. Rather than just another charting tool, Perspective for Java provides over 80 distinct chart types, 13 chart editing tools and a full set of properties and methods to give you complete control over the look and feel of a chart.

Review the Perspective for Java Complete Programmer’s Documentation

Open and flip through the over 400 page manual. Notice how every property and method is fully documented to show valid inputs, syntax and code examples. Every applicable property is also illustrated to show its effect on a given chart. Instructions are also given in detail on how the create a chart in HTML, a typical Java Development Environment as well as the various ways to link data to a chart.

Scan through the separate Chart Editor manual. It contains 5 full chapters detailing the chart editing widgets. Each widget is documented with instructions, descriptions, examples and illustrations. Every associated method is also listed so the user can duplicate chart settings in a development environment.

Perspective for Java is the only Java charting tool that includes such comprehensive and visual documentation. Users can consult the Programmer’s Manual as a quick reference to determine the type and how much functionality they want the charts to have.

All of the printed documentation as well as fully interactive JavaDoc is available at the Three D Graphics Web site at the following URL:

http://www.threedgraphics.com/javachart/doc_main.html

Check your System Before Using Perspective for Java

Perspective for Java is designed for use with Java 1.1 environments. When you are using a browser to develop charts, you must have a Java 1.1 compliant browser such as Internet Explorer 4.0 or Netscape Communicator 4.05 (with JDK 1.1 support). When you are developing with a JDE, you must have a 1.1 compliant Development Environment such as Symantec Visual Café. Since Perspective for Java is a JavaBean, it will not work with Java 1.0 or with earlier browser versions.

Note: Your system should be running in 24bit color for the charts in Perspective for Java to reach their full potential.

We recommend the following environments for development with Perspective for Java, however feel free to use whatever environments you are comfortable with.

1. Either Netscape Communicator 4.05 (with JDK pre-installed) or Microsoft Internet Explorer 4.01
2. JDK 1.1.5
3. Symantec Visual Café dbDE 2.5

Check the Three D Graphics Web Site for Latest Version

Perspective for Java is sold with the intention of being continuously updated on a weekly basis through the Three D Graphics Web site. After sale support is a very important aspect of Perspective for Java. Upon purchase, users can stay updated to new features and bug fixes by downloading the latest version.

Go to the Web site to check to see if the version that was sent to you is the latest one. All versions are noted by their build number. If you do not have the current build, go to the download page and get the "Complete Library With Editor." You will need to add the "TDGSecurity.class" file that you already have to the new .JAR file.

The Web site address is:

http://www.threedgraphics.com/tdg/products/tools/perspectivejava

Review Chart Design in the Perspective Chart Editor

The Perspective Chart Editor is our Java Application (it's also available in Applet form) for editing and saving charts. It has a complete user interface, written entirely in Java, consisting of various charting tools called widgets (see picture below). You use the "TDGLoadSave" application for loading, changing and saving chart templates for use in your web pages or Java applets. You can run "TDGChartEditorApplet" directly within your Intranet-based web page to give users complete editing control over the chart.

In Depth Look at the TDGLoadSave Application

1. First make a directory on your hard drive for all Perspective for Java files.
2. Unzip the "pfjfull.jar" file to access the "TDGLoadSave.class" file directly. We recommend using WinZip 6.3 to do this task.
3. Start the MS-DOS prompt and access the folder containing the Perspective for Java files.
4. Execute the "TDGLoadSave.class" by typing in the following command and pressing the Enter key.

java TDGLoadSave

Quick Tour of the Various Chart Types

Graph Type Widget

Click on the arrow pointing to the right to enter editing mode. Click the button for "Graph Type" and cycle through the various chart types. As you click on each type it will appear in the large window. Perspective for Java has 8 chart "groups" with many different types within each group. All chart types have icons and descriptions to help the user decide which is best for them.

Take a Look at Perspective for Java’s Outstanding 3D chart functionality

Chart Specific Widgets

Note: Some of Perspective Chart Editor’s widgets will change to reflect the chart type that is selected. These five examples illustrate the widgets when a 3D chart type is selected.

1. Click on the first type of 3D Bar chart.
2. Close the "Graph Type widget and Open "3D Chart Settings."
3. While the "Autoshading" checkbox is checked, move the X, Y and Z "Light Positions" and press Apply to see how moving the light source can change the view of a chart.
4. Open "3D Custom Viewing Angle" and "Rotate" the chart by clicking on the various arrows. Change some of the other views like "3D Pan", "Walls" and "Zoom." Make sure to click the Apply button after making the desired change in each field. You can view the chart at almost any angle, size and location.
5. Take a look at some of the "3D Preset Viewing Angles" that are included for a quick altered view of a 3D Chart.

The following list shows the different widgets for each chart type:

• 3D Charts – The "3D Chart Settings", "3D Custom Viewing Angle" and "3D Preset Viewing Angle" widgets appear as described above.
• Bar, Line and Area Charts – The "Bar, Line & Area Chart Settings", "Y1 Axis Settings" and "Group Axis Settings" widgets appear.
• Dual Y Charts – The "Dual Y Axis Settings", "Y1 Axis Settings" and "Y2 Axis Settings" widgets become active.
• Pie Charts – The "Pie Chart Settings" widget is added.

Change the Complete Design of a Chart in Minutes with Perspective for Java’s Widgets

The following steps will guide you with examples of simple changes to the look and feel of a chart. Feel free to explore the charting widgets in detail to create a chart that matches your style.

Apply Texture Fill Widget

• Click on the white background surrounding the chart so the edge is highlighted in yellow. Open the "Apply Texture Fill" widget, select the "Soft_Marble_Blue" texture and click Apply.

Apply Gradient Fill Widget

• Click on the background wall of the chart. Open "Apply Gradient Fill" and select the "Blue Tube", "Left" gradient.

Font Settings Widget

• Select all the Series and Data Label by clicking on a group and holding down the Shift key to select the others. Go to the "Font Settings" widget and select the Bold button.

Chart Titles Widget

• Go to "Chart Titles." Change the Chart Title to "Perspective for Java", change the Chart Subtitle to "Sales By Day" and delete the Footnote text. Click Apply when finished.

Color and Line Settings

• Select the "Perspective for Java" Title by clicking on it. Go to "Color and Line Settings" and choose a medium gray color. Go to "Font Settings" and select the button with the 2 s’ next to each other. This is gives the title a drop shadow effect.

Review the Loading and Saving Features in the TDGLoadSave Application

Perspective for Java writes out Java source code as its "file format", so you can cut and paste code to create charts directly into your own applications or HTML source. Perspective can also read its own text based files for use as chart templates with the "TDGLoadSave" application.

Quick Look at Writing and Loading Java Code in the Text Box

Choose "Output Properties as Different from Defaults" from the File menu. Perspective for Java will write the Java source code illustrating the changes you’ve made in the Text Box. You can cut and paste this code directly into the "TDGScript" parameter of an HTML file.

Choose " Restore Default Properties" from the File Menu. Now choose "Input Param Strings From Message Window" All code in the message window is read to create the specified chart.

Saving Chart Settings to a Text File

Select "Save Chart to a Text File" from the File Menu. Notice that you now have 3 options depending on the type of development you are doing.

1. "Save for Java Development" – This option will save chart settings with an object name that you specify for use in your Java Development Environment.
2. "Save for Loading via HTML" – This ignores any object name to generate code that can be easily pasted in an HTML source file.
3. "Save Difference From Default Settings" – This is the default option that saves just the changes you have made to a chart.

For our purposes, choose "Save for Loading via HTML" and choose the default "Save Difference from Default Settings" checkbox. Save the file under the name "test.txt."

Saving a Chart as a GIF Image

Select "Save Chart As GIF Image" from the File menu and save the chart to your desired location. Open the GIF file with your favorite photo editor to see the chart.

Loading a Chart Text File

Choose " Restore Default Properties" from the File Menu. Now choose "Load a Chart Text File" and select the "test.txt" file that you just saved. Your previous chart settings will now be illustrated in the chart.

Review the TDG Chart Editor Applet

Perspective for Java contains an applet called the "TDGChartEditor" which is used to design charts directly from within a web page. Users can create and save charts with the applet without leaving their web site or using any external development environment. The "TDGChartEditor" applet is very similar to the "LoadSave" application. All chart editing techniques are the same except for the loading and saving features.

Loading and Saving Differences between the TDGLoadSave Application and the TDGChartEditor Applet

The "TDGLoadSave" application allows you to load and save Java chart settings with the options listed above. The "TDGChartEditor" applet is restricted in this area due to the high security of loading and saving files over the internet. You are allowed to load and save text files as well as save a chart as a GIF, but only through an FTP Server.

Open the "TDGAppletEditorDemo1.html" file in the Perspective for Java source code for the following tests. You can also open a live Web version of this demo by clicking here.

Saving and loading charts through an FTP server with the TDGChartEditor Applet

Perspective for Java can save and load charts through an FTP server. This is a very useful tool for FTP users who need quick access to download charts. Note that due to server security configurations, the FTP machine must have the same physical IP address as the server in order to save and load GIF images.

Create GIF, Load and Save Widget

1. Open the "Create GIF, Load and Save" widget and choose the first tab.
2. Fill in the following fields with the respective information and click on the "Save Chart Image As GIF to File.
3. 
   
   FTP Host – This is the address of your FTP Server (i.e. ftp.earthlink.net).
   User ID and Password – Place a valid username and password in these fields.
   Directory – Put a path here if you want the files to be placed somewhere other than the FTP root directory.
   File name – Give your file a name.
4. Choose the second tab and select "Save Chart To Text As File."
5. Select the third tab and "Load Chart Text From File" choosing the same file that you just saved.

Review Perspective for Java Bean Capability in Development Environments

Perspective for Java’s full JavaBean support demonstrates its ease of use for even the novice Java developer. Once inserted into an applet or application, Perspective for Java appears with a full set of exposed properties. Each property can be changed to have an instant effect on a chart within the development environment.

The following section illustrates Perspective for Java as a JavaBean in Symantec Visual Café 2.5 and Borland JBuilder 1.0. These environments were chosen because they are the most commonly used in the Java market. Feel free to use whatever development environment you are comfortable with as long as it is Java 1.1 compliant.

Open Symantec Visual Café and View the Perspective for Java Bean

Select "New Project" from the File menu. When the New Project dialog appears, click on the "Basic Applet" icon to begin. Make the Visual Café Property List visible by selecting it in the View menu.

Note: In Visual Café 2.1, the Component Library and Property List appear under the Window menu.

Select "Component into Library" from the Insert menu and choose the "pfjfull.jar" file. Select "Component" from the Insert menu, scroll down the list and choose the exposed "Perspective" bean. A chart will magically appear before your eyes! Click on the edge of the chart and drag it to a desired size. Notice how the Visual Café Property List has changed to show all the Perspective for Java exposed properties with their default settings.

Note: You can drag and drop the "pfjfull.jar" file onto the Component Library and into the applet as an alternative to using the Insert menu.

Test and modify the applet including the Perspective for Java Bean

Now that you have created a basic applet including the Perspective for Java bean, its time to add some functionality to it.

Change some of the properties to see their effect on the chart

1. Scroll down the Property List to the "Graph Type" property. Type in "55" and press Enter. Notice that the chart in the applet has changed to a Pie chart.
2. Scroll down to the "ToolTipDisplay" property and change the value to "True." Execute the applet from the Project menu. Move to cursor over the pie slices to see the Tool Tips.
3. Go to the "PieTilt" property and change the value to "30." Take note of the change in the tilt of the pie.
4. Double click on the applet to view the code that Visual Café has generated based on the changes you made to the properties.

Add some other Java components to complete the charting applet

1. Drag a Button onto the space underneath the chart in the applet from the Standard toolbar.
2. Double click on the inserted button in the applet editor. Select "actionPerformed" in the Events/Methods section and paste the following code in the specified area.
3. 
   
   perspective1.setGraphType(0);
   perspective1.setTitleString("Perspective for Java");
   perspective1.setSubtitleString("Reviewer's Test");
4. Drag a checkbox next to the button from the Standard toolbar.
5. Double click on the inserted checkbox and select "ItemStateChanged" in the Events/Methods section. Paste the following code segment:
6. 
   
   if(checkbox1.getState()== true)
   perspective1.setToolTipDisplay(true);
   else perspective1.setToolTipDisplay(false);
7. Run the applet and test the button and checkbox. Notice how they change the chart based on your specifications.
8. Save the Visual Café project under the name "PFJCafeTest.vep" by choosing "Save All" from the File menu. This project will be used later in the reviewer’s guide.

Visual Café also includes a wizard to generate Java code to perform a simple action. To do this, right click on the button or checkbox, select "Add Interaction" and follow the directions.

Open Borland JBuilder and View the Perspective for Java Bean

Select "Configure Palette" from the Tools menu. When the Palette Properties dialog appears select the Add from Archive tab and browse for the "pfjbean.jar" file location. One the file is selected, click on the Install button and finally click OK. The Perspective for Java bean is now included in the Jbuilder component library.

Select "New" from the File menu and choose to create an applet. Take all of the default name settings in the proceeding dialogs and click Finish to start designing your applet. Click on the "applet1.java" file and select the Design tab to enter that mode. Click on the Perspective for Java icon in the component library and click on the grey area of the applet designer. Hold the mouse button and drag the cursor until you reach a desired size.

Test and modify the applet including the Perspective for Java Bean

Now that you have created a basic applet including the Perspective for Java bean, its time to add some functionality to it.

Change some of the properties to see their effect on the chart

1. Scroll down the Property List to the "Graph Type" property. Type in "55" and press Enter. Notice that the chart in the applet has changed to a Pie chart.
2. Scroll down to the "ToolTipDisplay" property and change the value to "True." Execute the applet from the Project menu. Move to cursor over the pie slices to see the Tool Tips.
3. Go to the "PieTilt" property and change the value to "30." Take note of the change in the tilt of the pie.
4. Choose the Source tab in the applet to view the code that JBuilder has generated based on the changes you made to the properties.

Add some other Java components to complete the charting applet

1. Drag a Button onto the grey area underneath the chart in the applet from the AWT toolbar.
2. Double click on the inserted button in the applet editor and paste the following code in the specified area.
3. 
   
   perspective1.setGraphType(0);
   perspective1.setTitleString("Perspective for Java");
   perspective1.setSubtitleString("Reviewer's Test");
4. Drag a checkbox next to the button from the AWT toolbar.
5. With the inserted checkbox selected, double click on "ItemStateChanged" in the Events tab and paste the following code segment:
6. 
   
   if(checkbox1.getState()== true)
   perspective1.setToolTipDisplay(true);
   else perspective1.setToolTipDisplay(false);
7. Run the applet and test the button and checkbox. Notice how they change the chart based on your specifications.
8. Save the JBuilder project under the name "JBuilderTest.jpr" by choosing "Save All" from the File menu.

Review Chart Design Using HTML

Perspective for Java supports an HTML parameter "TDGSCRIPT" which allows any number of methods to be posted to the chart applet from HTML. At a minimum, your HTML file must use the applet instruction(s) to identify the Perspective for Java.CLASS file and .JAR file that will be used to develop your chart.

Create an HTML Page Using a Perspective for Java Chart

1. Open your favorite HTML editor or just use a standard text editor.
2. Open the "test.txt" file you created with the "TDGLoadSave" application and paste all the generated code into the designated area below

   <APPLET
   CODE="TDGChartApplet.class"
   ARCHIVE="pfjfull.jar"
   WIDTH=640
   HEIGHT=480>
   <PARAM name=TDGSCRIPT value='
   setUseSampleData(true); /* This method is generating sample data to use in this example */
   ***PASTE ALL JAVA CODE FROM "TEST.TXT" HERE***
   </APPLET>

3. Save the HTML file you’ve created as "PFJChartAppletTest.html" Make sure this file is in the same directory as your .JAR file.
4. Double click on the HTML file you’ve created to run it in your default Web browser.
   

Perspective for Java offers full drill- down support

Perspective for Java’s URL methods allows you to include drill-downs in HTML files. When the user selects/clicks on an object in a chart where a "setURL" method is defined, the HTML file provided as an input parameter will automatically be loaded and displayed at the location specified by the "setURLTarget" method.

The following code segment illustrates the drill-down feature in Perspective for Java. To see this code in use on a live Web page go to http://www.threedgraphics.com/javachart/piedrill.html.

<APPLET CODE="TDGChartApplet.class" ARCHIVE="pfjbean.jar" WIDTH="400" HEIGHT="280">
<PARAM NAME="TDGSCRIPT" VALUE="
setTitleString("Pie Chart with Drilldown"); /* Set the Title String */
setSubtitleString("Click on the slices to see a description");
setGraphType(55); /* Set the graph type to Pie */
setSeriesLabelArray("Monday", "Tuesday", "Wednesday", "Thursday", "Friday");
setDataSeries(35.00);
setDataSeries(27.00);
setDataSeries(15.00);
setDataSeries(17.00);
setDataSeries(27.00);
setURL(0,0,"series0.html");
setURL(1, 0,"series1.html");
setURL(2, 0,"series2.html");
setURL(3, 0,"series3.html");
setURL(4, 0,"series4.html");
setURLTarget(0,0, "Bottom");
setURLTarget(1,0, "Bottom");
setURLTarget(2,0, "Bottom");
setURLTarget(3,0, "Bottom");
setURLTarget(4,0, "Bottom");
setToolTipDisplay(true); ">
</APPLET> </P>

Review Using Your Data in a Chart

One of the main features of Perspective for Java is the various ways to link data to a chart. Perspective provides built-in sample data that will be used until and unless you set up your own data source. The sample data is used so you can insert the Bean or Applet into a development environment or web page and instantly see a chart without connecting your own data.

Perspective for Java supports several methods for connecting your data. These can be very useful depending on the specific situation.

Loading Data from a File

Open the "TDGAppletDemo1.html" file in the Samples folder with your favorite browser. Make sure that the HTML file is in the same directory as the "pfjfull.jar" file. Right click anywhere within the page outside of the applet and select "View Source." The "setDataFileURL("states_spending.txt");" line is setting the chart data to be the designated file.

The contents of the "states_spending.txt" file can be easily imported since it is comma delimited. Here are the contents of the file:

"labels","1990","1991","1992","1993","1994","1995","1996","1997","1998"
"States",.07,.045,.05,.03,.05,.06,.05,.042,.05
"Federal",.09,.05,.042,.02,.037,.037,.03,.026,.02

Note: You can also list the data without labels.

Loading Data Directly Inside an HTML File

1. Open the "TDGAppletDemo1.html" file with an HTML or text editor. Replace the "setDataFileURL…" line with the following code:
2. 
   
   setSeriesLabelArray("States","Federal");
   setGroupLabelArray("1990","1991","1992","1993","1994","1995","1996"," 1997","1998");
   setDataSeries(.07,.045,.05,.03,.05,.06,.05,.042,.05); /*States*/
   setDataSeries(.09,.05,.042,.02,.037,.037,.03,.026,.02); /*Federal*/
3. Save the changes to the HTML file and run it in a browser. The same chart will appear, however the data is now set by the "setDataSeries.." method directly in the HTML source instead of being linked to a file via the "setDataFileURL.." method.

Loading Data from a Database

Perspective for Java allows you to link to an ODBC database as the source for chart data. The following example illustrates linking to a Microsoft Access database. Feel free to use whatever type of database available to you to demonstrate Perspective for Java’s ODBC connectivity.

1. Install the ODBC Administator located in the ODBC folder on your Perspective for Java CD. Please note that the version contained on the CD is for Intel platforms. If you need a different version go to the Microsoft Web site at the following URL: http://www.microsoft.com/data/odbc/
2. Run the "32bit ODBC Administrator" after installation.
3. Select the "MS Access 97 database" driver and click on the Configure button.
4. Click on the Select button and browse for the location of the "JDBCDataBaseDemo.mdb" file on your hard drive. Click OK twice to exit out of the Administrator.
5. Open the MS-DOS Prompt or appropriate command line and access the directory on your hard drive that contains the "JDBCDataBaseDemo.html" file. This file must be in the same directory as your Perspective for Java files.
6. Paste the following text in the command line: "appletviewer JDBCDataBaseDemo.html"
7. Paste the following select statement in the text window and click on the JDBC Data Import button.

"select name, unit_price from products"

Notice that a new chart is drawn corresponding to the data selected in the database.

Loading Data from Java

Perspective for Java can use data coded directly into Java source to create a chart. There are 3 ways to do this: "TDGDataGrid", The "CallBackTechnique" and Individual Values. For a detailed description of the first two methods see pages 6-4 to 6-6 of the Perspective for Java Programmer’s Manual. The following will illustrate how to set individual values using Java source code.

1. Open the Visual Café Project "PFJCafeTest.vep" that you saved earlier. Double click on the "Applet1" icon in the Project window to change to editing mode.
2. Double click on the chart to bring up the source code window.
3. Paste the following code right above the "add(perspective1);" line.
4. 
   
   perspective1.setUseSampleData(false);
   perspective1.setTitleString("Three D Graphics Sales");
   perspective1.setSubtitleString("January");
   perspective1.setFootnoteDisplay(false);
   perspective1.setGroupLabel(0, "Jan");
   perspective1.setSeriesLabel(0, "Jon");
   perspective1.setSeriesLabel(1, "Don");
   perspective1.setSeriesLabel(2, "Joe");
   perspective1.setSeriesLabel(3, "Eric");
   perspective1.setSeriesLabel(4, "Sam");
   perspective1.setData(0,0,10);
   perspective1.setData(1,0,22);
   perspective1.setData(2,0,44);
   perspective1.setData(3,0,71);
   perspective1.setData(4,0,62);
5. Select "Execute" from the Project menu. Your new data will now be in the chart.

Conclusion

Perspective for Java combines the extraordinary world of 2D and 3D charting, plus the flexibility of Java development in one complete library. With powerful features like those listed below, Perspective for Java makes developing a chart a breeze.

• 86 different chart types including various types of 3D, bar, line, area and pie. PFJ also includes more esoteric charts like radar, polar, bubble and histogram.
• Link to data from any source: HTML, JDBC, text files, live data via a class or method and many more.
• Full Property and Method based API for use as either a JavaBean or as a class library.
• Complete chart editing user interface in both applet and application form.
• Built-in drill –down support allows specification of URL and target for every single data point.
• Comprehensive printed, HTML and JavaDoc documentation.
• Complete gradient, texture, picture and clipart support for all charts.
• Works with any true Java 1.1 development environment or browser.
• ToolTips for every element and user interface widget.
• Cut and paste Perspective for Java source code for use in your own applications.

Perspective for Java is a must have for any business looking to display corporate data via the Web or internal network.

Appendix:

Perspective for Java Properties and Methods

Here is the complete list of the properties and methods used in Perspective for Java to develop a chart. Each one has a short description detailing its usage.

Properties

The following table briefly describes all of the properties that are currently supported in the "Perspective.class" JavaBean. If you are not using a Bean editor, add "set" or "get" as a prefix to each property name to use the property as a method (e.g., Autoshading = getAutoshading(); or setAutoshading( true | false );). See Chapter 7 in the Perspective for Java Programmer’s Guide for a complete description of these properties and an example of how each property is used.

Methods

The following table briefly describes each of the methods that are included in Perspective.class. Also see Chapter 4 for additional methods that are for HTML development only. See Chapter 8 in the Perspective for Java Programmer’s Guide for a complete description of each method.