GraphLibraryExportFeatureAPIReview

Graph Library Export Feature API Review

Submitter: Kris.Richards@Sun.COM

Type: Fast Track

Short Description

This addition to the Graph Library API is absolutely trivial. The request is to add a convenience class (within a separate package) to allow users to export a Scene to any of a defined set of formats. This export class would also contain functionality to return to polygonal points for each widget that is a child of the layers on the scene.

Target Milestone

NetBeans 6.1

Dependencies

There are currently no dependencies on this addition. These new classes depend only on standard JDK classes.

Change in Current Architecture

The current architecture exposes org.netbeans.api.visual to other modules. The implementations are hidden in the org.netbeans.modules.visual package. The plan is to add a package, export, to the api package which will contain two final classes, SceneExporter and WidgetPolygonalCoordinates. SceneExporter will contain two public enumerations, ImageType and ZoomType. The ImageType simply contains the file types currently supported by the feature. If additional formats are to be added in the future, the enumeration will be the only item in the public API requiring alteration, all the major code changes will occur in the implementation classes. The ZoomType contains the various strategies for painting the image. The class, WidgetPolygonalCoordinates, is a simple class to hold a widget and an assosciated polynomial which fully encompasses the widget. An ArrayList of these WidgetPolygonalCoordinates is returned when the createImageMap method is called (see below).

There are two public static methods in the SceneExported: createImage, and createImageMap.

  • public static BufferedImage createImage(Scene scene, File file, ImageType imageType, ZoomType zoomType, boolean visibleAreaOnly, boolean selectedOnly, int quality, int width, int height) throws IOException
  • Takes the Scene and writes an image file according to the constraints defined by the caller. This returns a BufferedImage of the Scene even if the file can not be written.
  • @param scene The Scene to be exported as an image.
  • @param file The file used to store the exported image. If null, then it is assumed that the raw image is to be returned only and not written to a file.
  • @param SceneExporter.ImageType The image type to be exported for the image map.
  • @param SceneExporter.ZoomType Defines the strategy by which to set the exporting scale factor. Note that certain parameters are nullified by the choice of ZoomType. For instance, if ZoomType.CUSTOM_SIZE is not chosen, then the width and height parameters are not used.
  • @param visibleAreaOnly Eliminates all zoom features. If true, the exported image will be a created from the visible area of the scene.
  • @param selectedOnly Create an image including only the objects selected on the scene. Note that this feature requires that the scene is an instance of an ObjectScene since it is the implementation that allows for object selection.
  • @param quality And integer value between 0-100. This is for JPG images only. Parameter is not used if an image type other than jpg is selected.
  • @param width Directly sets the horizontal dimension of the exported image. This is only used when the zoomType is ZoomType.CUSTOM_SIZE
  • @param height Directly sets the vertical dimension of the exported image. This is only used when the zoomType is ZoomType.CUSTOM_SIZE.
  • @return image The raw image that was written to the file.
  • @throws java.io.IOException If for some reason the file cannot be written, an IOExeption will be thrown.
  • public static ArrayList<WidgetPolygonalCoordinates> createImageMap(Scene scene, File file, ImageType imageType, ZoomType zoomType, boolean visibleAreaOnly, boolean selectedOnly, int quality, int width, int height, int margin) throws IOException
  • Designed to create an HTML image map from an exported image. Each Layer in the Scene provided to the constructor is iterated over and a java.awt.Polygon is created surrounding each Widget contained in the layers. A WidgetPolygonalCoordinates is created to hold the Widget and Polygon.
  • @param scene The Scene to be exported as an image. The Widgets will be collected from this scene and polygons create that wrap each widget. The coordinates of each polygon are stored in an instance of WidgetPolygonalCoordinates.
  • @param file The file used to store the exported image. If null, the method immediately returns null.
  • @param SceneExporter.ImageType The image type to be exported for the image map.
  • @param SceneExporter.ZoomType Defines the strategy by which to set the exporting scale factor. Note that certain parameters are nullified by the choice of ZoomType. For instance, if ZoomType.CUSTOM_SIZE is not chosen, then the width and height parameters are not used.
  • @param visibleAreaOnly Eliminates all zoom features. If true, the exported image will be a created from the visible area of the scene.
  • @param selectedOnly Create an image including only the objects selected on the scene. Note that this feature requires that the scene is an instance of an ObjectScene since it is the implementation that allows for object selection.
  • @param quality And integer value between 0-100. This is for JPG images only. Parameter is not used if an image type other than jpg is selected.
  • @param width Directly sets the horizontal dimension of the exported image. This is only used when the zoomType is ZoomType.CUSTOM_SIZE
  • @param height Directly sets the vertical dimension of the exported image. This is only used when the zoomType is ZoomType.CUSTOM_SIZE.
  • @param margin The size of the clickable margin around each connection. This is meant for defining the sensitivity of the links around the connection objects. Note that the area around the node objects is not affected by this margin.
  • @return ArrayList of WidgetPolygonalCoordinates objects which are simply used to hold a Widget and Polygon. From the calling class, the widget and coordinates can be used to create a link for the widget on an HTML image map.
  • @throws java.io.IOException If for some reason the file cannot be written, an IOExeption will be thrown.


The two enumerations in the SceneExporter are:

  • ImageType - contain the values: JPG and PNG
  • ZoomType - contain the values:
  • CUSTOM_SIZE - Used to set the horizontal and vertical sizes directly.
  • FIT_IN_WINDOW - Used when the objects in the scene are to be exported into an image with the identical dimensions of the scene's visual window.
  • CURRENT_ZOOM_LEVEL - Used when the objects in the scene are to be exported into an image scaled the same as the scene.
  • ACTUAL_SIZE - Used to export an image of the scene according to its boundary dimensions.


Use Cases

  1. User wants to export a Scene into an image file
    1. Exactly as it is with and without the Scene's current zoom
    2. Confined to the visible window
    3. Confined to a specific size (region starting from (0, 0) )
    4. Confined to selected objects
  2. User wants HTML Image Map coordinates of an exported Scene image file to use is some sort of web report. Note that an image is written according to the constraints list in the previous point.
  3. User wants a BufferedImage of a Scene for whatever purpose. By simply sending a null as the file parameter, the write will fail and the BufferedImage will be returned.


Summary of Changes (see org.netbeans.api.visual.export package in attached Javadoc, org-netbeans-api-visual_GraphLibraryExportFeatureAPIReview.zip)

  • adding (public) (see code in API_Export_GraphLibraryExportFeatureAPIReview.zip):
  • org.netbeans.api.visual.export.SceneExporter
  • org.netbeans.api.visual.export.SceneExporter.ImageType
  • org.netbeans.api.visual.export.SceneExporter.ZoomType
  • org.netbeans.api.visual.export.WidgetPolygonalCoordinates
  • adding (private) (see code in Module_Export_GraphLibraryExportFeatureAPIReview.zip):
  • org.netbeans.modules.visual.export.Scene2Image

apichanges.xml

   <change>
            <api name="general"/>
            <summary>Add scene export feature.</summary>
            <version major="2" minor="10"/>
            <date day="26" month="2" year="2008"/>
            <author login="krichards"/>
            <compatibility addition="yes"/>
            <description>
                Added a convenience class, SceneExporter, to allow users to export a Scene to any of a defined set of formats. This 
                export class would also contain functionality to return to polygonal points for each widget that is a child of the 
                layers on the scene.
            </description>
            <package name="org.netbeans.api.visual.export" link="yes"/>
            <issue number="128387"/>
   </change>

Impacted Interfaces

There are no current interfaces being impacted by this addition

Change Sets

http://hg.netbeans.org/uml-meteora/rev/054b28bcda31

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo