Version 1.9.1

CgmCanvas and CgmSwt

by Berthold Daum
June 2007

• Functionality
  
• API
  
• Examples
  
• Installation
  
• Ordering
  

Functionality

The CGM Canvas library provides almost the same functionality for Java Swing applications as the CGM Viewer Applet (cgmVA) for web applications. For a description of cgmVA see here. cgmVA can be downloaded from here.

The CGM SWT library provides the same functionality for SWT based platforms, such as applications based on the Eclipse Rich Client Platform.

The CGM Panel allows to embed CGM graphics into Java2 applications.

What are the differences compared to cgmVA?

CgmCanvas and CgmSwt do not support the parameters

• nosplash. This is because the splash screen normally does not appear. Instead, a splash screen can be invoked by supplying the empty parameter string to CgmPanel.
  
• eventHandler. This is because we do not need to support JavaScript.

CgmCanvas and CgmSwt offer the following additional functionality:

• antialiasing parameter. This parameter can be set to on or off to enable or disable antialiasing. If not specified the system default applies.
  
• setParameters method. This method is used to set the parameters of a CgmPanel object. All parameters are specified within a single string. The syntax is 
  parametername=value, individual parameters are separated by a blank.
  
  Note: Because the blank character is used as a delimiter you must enclose parameter values that contain strings into double quotes such as:
  parametername=\"value\"
  Remember that file names can contain blanks, so it is good practice to wrap file names into double quotes:
  filename='"'+filename+'"'; 
  
  File names can be specified as absolute URLs (if necessary with the file: protocol prefix), or as URLs relative to the users working directory.
  
• addStatusListener and removeStatusListener methods. Used to register and deregister a StatusListener object with a CgmPanel object. The CgmPanel object will use this StatusListener's showStatus method to display status messages. The library class StatusLine implements the StatusListener object and can be used for this purpose.
  
• addLinkListener and removeLinkListener methods. Used to register and deregister a LinkListener object with a CgmPanel object. The CgmPanel object will call the LinkListener's linkClicked method when a hyperlink was clicked.
  
• addScrollBars method. Used to notify a CgmPanel object about the presence of scroll bars. This method is used by the class CgmScrollPanel.
  
• print method. This method allows to print the content of the panel. A parameter can be used to specify the printing mode:
  • PRINT_FITTING prints the visible area fitting onto one page.
  • PRINT_TILED prints the visible area in original size, tiling onto several pages if necessary.
  • PRINT_TILED_CANVAS prints the whole drawing in original size, tiling onto several pages if necessary.
    
• eventXtoCgmX and eventYtoCgmY methods. Convert event coordinates to CGM coordinates (0..1000).
  
• CgmXtoEventX and CgmYtoEventY methods. Convert CGM coordinates (0..1000) to event coordinates.
  
• (New in 1.7) Methods for the configuration of user actions. The default behaviour regarding mouse clicks is similar to that of cgmVA. However, it is possible to configure mouse actions. The method configureMouseAction can assign to each operation such as ZOOM_IN, ZOOM_OUT or PAN a specific modifier key. Note, that the animation event mask must be set accordingly in order not to steal mouse events (setEventMask). The method setDragTolerance can be used to specify a threshold value for mouse drag operations.
  In addition, the method configureKeyAction can assign combinations of key presses and modifier keys to operations. This is to improve accessibility as it becomes possible to operate cgmPanel without the use of a mouse. The method configureArrowKeys can be used to assign scroll increment values to the arrow keys.
  All these methods must be called after setParams was called.
  

CgmCanvas and CgmSwt also improves some of the existing features of cgmVA:

• In addition to GIF bitmap files it is now possible to use JPeG and PNG files, too.
• In addition to AU audio files it is now possible to use also AIF, RMF, and WAV.
• Rotated text can now be displayed with non-Hershey fonts, too.

top

API

The CGM Panel API consists of three top level classes and two interfaces:

• CgmPanel extends the JPanel class with the methods discussed above and implements the following Java standard interfaces: MouseListener, MouseMotionListener, and Printable. The usual JPanel methods can be used to set the initial size of the component (setPreferredSize(Dimension dim)) or to redraw the component (repaint()).
  
• CgmScrollPanel extends the JPanel class. It adds the method replaceContent(CgmPanel c) to replace an existing CgmPanel object with a new one, and the method setAnimated(boolean a) to control the behavior of the scroll bars. If this property is set to true, the content will be redrawn while scrollbars are moving, if false, the content will be redrawn after the scrollbars have been moved.
  CgmScrollPanel implements the interfaces AdjustmentListener and ChangeListener. The ChangeListener methods allow to listen to JSlider events and control the zoom level of the content.
  A CgmScrollPanel object is constructed invoking its new method and passing a CgmPanel object as argument.
  
• StatusLine extends the JPanel class. It adds the method setFont(String fontname, int fontstyle) to control the display font, and the method showStatus(String message) to display a message. The JPanel method setPreferredSize(Dimension dim) can be used to set the initial size of a StatusLine object. 
  StatusLine can animate messages. When a message does not fit into the line width, it message is scrolled around in an automated manner.
  StatusLine implements the StatusListener interface.
  
• StatusListener is an interface that must be implemented by objects that are added to a CgmPanel object with the addStatusListener method. StatusListener objects must implement the showStatus method.
  
• LinkListener is an interface that must be implemented by objects that are added to a CgmPanel object with the addLinkListener method. LinkListener objects must implement the linkClicked method.
  

The full API documentation is found here.

top

Examples

For the Swing version we have implemented three examples to demonstrate the usage of the CGM Panel class library.

• CgmViewer is a simple CGM Viewer. It uses the same navigation techniques as the CGM applet. It demonstrates how to register a CgmPanel as a MouseListener and MouseMotionListener, how to process clicks to hyperlinks and status messages, and illustrates the different printing modi.

• CgmScrollViewer demonstrates the cooperation between CgmPanel objects and CgmScrollPanel objects. Navigation happens here with the help of scroll bars and zooming is controlled via a JSlider object.

Both viewers can be well used as stand-alone Java CGM Viewers.

• ExampleAnimation implements the same animation as know from the CGM applet. Instead of using JavaScript calls, Java method calls are used to control the animation. However, there is one major difference: While in the JavaScript implementation of the CGM applet, the JavaScript function had to poll the applet for mouse events, processing is here completely event based. Mouse events will simply trigger the MouseListener and MouseMotionListener methods implemented in the example. No polling is required. Note that both the CgmPanel object and the ExampleAnimation object are registered as MouseListeners and MouseMotionListeners.

• The class SvgExporter demonstrates how to export a CGM drawing into SVG file. This class makes use of Apache Batik which is not included in this package. It can be obtained from www.apache.org. If you have installed the Batik modules you can use CgmViewer to convert from CGM to SVG. Please see SvgExporter.java for further information.

• The class PngExporter demonstrates how to export a CGM drawing into a PNG image file. This class requires JDK 1.4.0 or later. Please see PngExporter.java for further information.

For the SWT version we have implemented an Eclipse plugin that displays CGM images in the Eclipse editor area.

Installation

To use the CGM Panel classes, simply place the files cgmpanel.jar and cgmpanelregistration.jar into your class path. To run the examples, place also the directory containing the example .class files into your class path. The command files (Windows2000) CgmViewer.cmd, CgmScrollViewer.cmd and ExampleAnimation.cmd show how this is done.

To run the animation example, you must also place the folder cgmAnimationDemo into your working directory. If you don't know where this is, just run the example and the console output will tell you where the files are expected.

Ordering

The downloaded version is a demo version displaying the string "Demo" across the panel. To obtain a fully functional version, please register the product. CGM Panel can be registered at

http://www.reg.net/product.asp?ID=10445

or by calling 1 800 WWW2REG (1 800 999-2734) or (661) 288-1827 (USA).

The price for registration is USD 99.00. After registration you will receive a key in a new cgmpanelregistration.jar file that will unlock the full functionality. The license covers both the Swing and SWT version (CgmCanvas and CgmSwt) and entitles you to redistribute these packages within the context of your own applications.

top