/* Copyright (c) 2006-2009 Pearl Crescent, LLC.  All Rights Reserved. */

#include "nsISupports.idl"
#include "nsIDOMWindow.idl"
#include "nsILocalFile.idl"

[scriptable, uuid(b68c6e91-62fa-49ed-95b6-616dc3ba5123)]
interface pagesaverICapturePageImage : nsISupports
{
  /* Possible values for aCapturePortion. */
  const short PORTION_VISIBLE = 0;
  const short PORTION_ENTIRE  = 1;
  const short PORTION_SELECTED  = 2;

  /* Possible values for aDestination. */
  const short DESTINATION_DEFAULT   = -2;
  const short DESTINATION_CLIPBOARD = -1;
  const short DESTINATION_LOCALFILE =  0;
  const short DESTINATION_SERVER1   =  1;

  /*
   * Status codes.
   * Each call to capturePageImage() will generate a notification with
   * the topic "PageSaver:CaptureComplete".  The subject of the notification
   * will be the window whose contents were captured and the data string will
   * begin with one of the following status codes (the data string may include
   * an optional text error message; if present, it will follow the status code
   * and be separated from it by a '-' character).
   */
  const short STATUS_SUCCESS = 0;
  const short STATUS_CANCELLED = 1;
  const short STATUS_NO_INTERACTION_ALLOWED = 2;
  const short STATUS_INVALID_ARG = 3;
  const short STATUS_NO_CANVAS = 4;
  const short STATUS_CANVAS_DRAWING_ERROR = 5;
  const short STATUS_CANVAS_STREAM_ERROR = 6;
  const short STATUS_INVALID_FILE_PATH = 7;
  const short STATUS_FILE_OUTPUT_ERROR = 8;
  const short STATUS_UPLOAD_ERROR = 9;
  const short STATUS_CLIPBOARD_ERROR = 10;
  const short STATUS_ELEMENT_NOT_FOUND = 11;
  const short STATUS_REQUEST_ERROR = 12;

  /* Capture a PNG image of a page.
   *
   * @param aContentWindow
   *        The window whose contents will be captured.
   * @param aCapturePortion
   *        The portion of the page to capture, either PORTION_VISIBLE,
   *        PORTION_ENTIRE, or PORTION_SELECTED.
   * @param aDestination
   *        The location where the image will be saved.  To use the configured
   *        Page Saver default location, specify DESTINATION_DEFAULT.
   * @param aDestObj
   *        Pass an nsILocalFile object to specify the destination file or
   *        directory path.  Pass an nsIURI to specify the destination URI as
   *        an ftp, http, or https URI.  If aDestObj is not null, the value of
   *        the aDestination parameter is ignored.
   * @param aOptions
   *        A comma-separated list of options (may be null).  The available
   *        options are:
   *          noInteraction         - do not prompt the user, play sounds, etc.
   *          closeWhenDone         - close window after capture is complete.
   *          exitWhenDone          - exit Firefox after capture is complete.
   *          top=<pixelval>        - omit from the captured image the first
   *                                    pixelval pixels along the top of page.
   *          left=<pixelval>       - omit from the captured image the first
   *                                    pixelval pixels along the left side of
   *                                    the page.
   *          bottom=<pixelval>     - crop the captured image along the bottom
   *                                    at pixelval pixels.  If pixelval is a
   *                                    negative number, crop at pixelval
   *                                    pixels from the bottom.
   *          right=<pixelval>      - crop the captured image along the right
   *                                    side at pixelval pixels.  If pixelval
   *                                    is a negative number, crop at pixelval
   *                                    pixels from the right side.
   *          element=<id>          - the id of an element to be captured.
   *          scale=<scaleval>      - reduce or limit the size of the captured
   *                                    image.  If scaleval ends with a %
   *                                    character, the image is scaled to the
   *                                    specified percentage.  If scaleval is a
   *                                    simple integer, the largest dimension
   *                                    of the resulting image will at most
   *                                    scaleval pixels.
   *          format=<contenttype>  - specify the format of the saved image.
   *                                    The contenttype may include options.
   *                                    Examples:
   *                                       format=image/jpeg
   *                                       format=image/jpeg@quality=75
   *                                       format=image/png
   *                                       format=image/png@transparency=none
   */
  void capturePageImage(in nsIDOMWindow aContentWindow,
                        in short aCapturePortion,
                        in short aDestination,
                        in nsISupports aDestObj,
                        in string aOptions);

  /* Is the capturePageImage() API available? */
  readonly attribute boolean canCapture;
};