File Handling

Class SaveHandler

The yFiles FLEX remote API offers a class to save a graph as GraphML file locally.

The SaveHandler opens a file dialog and saves the graph as GraphML in the selected file. Example 4.14, “Using SaveHandler” shows a basic usage example of class SaveHandler.

Example 4.14. Using SaveHandler

// Create a SaveHandler
var saveHandler:SaveHandler = new SaveHandler();

// save the file.
// 'graphCanvas' is of type com.yworks.ui.GraphCanvasComponent.
saveHandler.save(graphCanvas.graph, "theGraph.graphml");

Note

Starting with Flash Player 10, opening a file dialog is only allowed as consequence of a user interaction, e.g. after clicking a button or pressing a key. To ensure compatibility with Flash Player 10, we recommend to use SaveHandler's save method only in a method which is called as a result from a user interaction. Calling save from e.g. the initialization method or a result handler from a HttpService will be treated as a security violation by Flash Player.

The yFiles FLEX API offers a similar class which can be used to send the graph as GraphML to a server and save the response in a file. See the section called “Class DownloadHandler” for details.

Configuring SaveHandler

The SaveHandler delegates the serialization process to a GraphMLIOHandler. By default, this handler is created by the protected method createOutputIOHandler(). It is possible to customize the SaveHandler (e.g. adding mapper attributes or using a JavaCompatGraphMLIOHandler) by replacing this output handler.

There are two ways to set a customized output handler: passing a RoundtripHandler instance as the constructor's optional parameter roundtripHandler or setting a GraphMLIOHandler instance to the outputIOHandler property. The RoundtripHandler can be configured as shown above in the section called “Class RoundtripHandler”. It is possible and convenient to use the same RoundtripHandler instance as used for roundtripping.

Constructor
API
SaveHandler(roundtripHandler:RoundtripHandler = null)
Description The constructor can be used to pass a custom RoundtripHandler which serves as a factory to retrieve a configured GraphMLIOHandler as outputIOHandler.
IO Handler
API
outputIOHandler:GraphMLIOHandler
Description The GraphMLIOHandler that will be used for graph serialization. A custom set of GraphML output handlers can be used for serialization by either setting a configured GraphMLIOHandler or by adding/removing output handlers to/from the GraphMLIOHandler instance used by the RoundtripHandler.

Subclassing SaveHandler

For common file save requests, class SaveHandler can be used directly. Nevertheless, if custom event handling of download requests is needed, the SaveHandler offers protected event handlers for all events that may occur during a save request which may be overriden.

Class LoadHandler

Class LoadHandler makes it easy to load a GraphML file from the local file system into a yFiles FLEX application. Example 4.15, “Using LoadHandler” shows a basic usage example of class LoadHandler.

Example 4.15. Using LoadHandler

  // Create a LoadHandler
  var loadHandler:LoadHandler = new LoadHandler();

  // Show a file chooser, load the selected file,
  // and display it in the canvas.
  loadHandler.load(graphCanvas.graph);
  

Note

Starting with Flash Player 10, opening a file dialog is only allowed as consequence of a user interaction, e.g. after clicking a button or pressing a key. To ensure compatibility with Flash Player 10, we recommend to use LoadHandler's load method only in a method which is called as a result from a user interaction. Calling load from e.g. the initialization method or a result handler from a HttpService will be treated as a security violation by Flash Player.

The yFiles FLEX API offers a similar class which can be used to upload a GraphML file to a server and send the response to the client. See the section called “Class UploadHandler” for details.

Configuring LoadHandler

Class LoadHandler offers various methods and properties for configuring the load and deserialization process of the GraphML file:

inputIOHandler:GraphMLIOHandler
Description The GraphMLIOHandler that will be used for graph deserialization.
roundtripHandler:RoundtripHandler
Description The RoundtripHandler instance that is used for graph deserialization. If no graph was passed to the upload method it is also used to automatically update the graph canvas which is handled by the RoundtripHandler.
fileFilter:Array
Description A filter that determines the files that can be chosen with the file chooser.

Class ImageSaveHandler

Class ImageSaveHandler creates a bitmap representation of the graph canvas and saves it to a file. Example 4.16, “Using ImageSaveHandler” shows a basic usage example of class ImageSaveHandler.

In general, to make sure that asynchronous content is exported correctly, a sprite containing the canvas content should be passed using the canvasSprite parameter. For example, if an ImageNodeStyle is used with a remote SWF, the SWF will not be visible in the exported bitmap if this method is called directly without passing a pre-rendered sprite. Also, as this method will use a Flex FileReference instance to open a save dialog, this method should only be called in direct response to a user event (e.g. a mouse click or keypress handler). Otherwise, a security error will be thrown. The below example shows how the export function can be called with a pre-rendered sprite.

Example 4.16. Using ImageSaveHandler

  // create a sprite containing the canvas content
  var printSprite:PrintSprite = canvasComponent.createSprite();

  // create a dialog that will not be shown until the sprite has finished rendering
  // any asynchronous content. As an alternative, we could also show the dialog immediately,
  // but enable the dialogs' submit button only when the canvas has finished rendering.
  var dialog:MyDialog = new MyExportDialog();
  dialog.addEventListener(MyDialogEvent.OK,function(evt:MyDialogEvent):void {
    // When a submit button is pressed in the custom dialog, this event is dispatched.
    // We can now call the export function in direct response to the user event
    // (mouse click on the ok button).
    new ImageSaveHandler().export(canvasComponent, "export.png", myExportOptions, printSprite);
  });

  if(!printSprite.paintComplete) {
    var onPaintComplete:Function = function(evt:Event):void {
      printSprite.removeEventListener(Event.COMPLETE,onPaintComplete);
      showDialog(dialog);
    };
    printSprite.addEventListener(Event.COMPLETE,onPaintComplete);
  } else {
    showDialog(dialog);
  }
  

The image export is started by calling the export() method. Its parameter canvas defines the CanvasComponent to get the image from, the parameter exportOptions can be used to configure the export using an ExportOptions instance as explained below.

The yFiles FLEX API offers a similar class which can be used to send a bitmap image file to a server and send the response to the client. See the section called “Class ImageExportHandler” for details.

Class ExportOptions

The image export can be configured by passing an instance of the class ExportOptions to the export() method.

backgroundColor:uint
Description The custom background color to be used for the export.
hasBackground:Boolean
Description Whether a custom background should be drawn.
insets:IRectangle
Description A rectangle that describes the insets.
maxHeight:uint
Description The maximum height of the exported document.
maxWidth:uint
Description The maximum width of the exported document.

The scaleMode:uint property determines how to scale the contents of the exported document. It uses one of the ExportOptions.SCALE_MODE constants:

SCALE_MODE_NONE
Description Use the natural size of the exported content.
SCALE_MODE_FIT
Description Fit the exported content to the bounds determined by the maxWidth and maxHeight properties. If only one of both properties is set to a value > 0, the other dimension will be chosen as appropriate.
SCALE_MODE_VIEWPORT
Description Use the visible area and zoom factor determined by the current view port.
An instance with the default settings can be obtained using the static method defaultOptions.

Subclassing ImageSaveHandler

If custom event handling of export requests is needed, the ImageSaveHandler offers event listeners for all events that may occur during an export request may be overriden.

To chose a different image encoding, the method encodeBitmap() can be overridden as shown in Example 4.17, “Overriding encodeBitmap to encode a JPEG image”.

Example 4.17. Overriding encodeBitmap to encode a JPEG image

public class JpegExportHandler extends ImageSaveHandler
{
  public function JpegExportHandler()	{
    super();
  }

  // delegate to a mx.graphics.codec.JPEGEncoder to encode the bitmap
  override protected function encodeBitmap(bitmap:BitmapData):ByteArray {
    return new JPEGEncoder().encode(bitmap);
  }

}