/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is mozilla.org Code.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 2001
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Rusty Lynch <rusty.lynch@intel.com>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */
/* 
 * Defines scriptable interface to SANE plugin.
 */

#include "nsISupports.idl"

[scriptable, uuid(10982800-365e-11d3-a2bf-0004ac779ef3)]
/**
 * This interface can be obtained with the following HTML/JavaScript sequence:
 *
 * <pre>
 * <EMBED type="application/X-sane-plugin" 
 *        id="SaneObject" 
 *        onScanComplete="ScanCompleteCallback()"
 *        device="hp:/dev/usbscanner"
 *        line_width="5"
 *        line_style="dash"
 *        cap_style="round"
 *        join_style="round"
 *        width=320 height=240>
 *
 * <form name="myForm">
 *   <!-- Scan Selected Region -->
 *   <input type="button" 
 *          value="Start Scan" 
 *          onClick="scanner.ScanImage()">
 *   <!-- many more buttons for controlling scanner/camera... -->
 * </form>
 * <script>
 *  var scanner = document.SaneObject.nsISaneControl;
 *  dump("scanner = "+ scanner + "\n");
 * </script>
 * </pre>
 *
 * This fragment will create an embedded plugin, which can then be accessed
 * and controlled by the nsISanePluginInstance interface which is instantiated
 * in the script.
 */
interface nsISanePluginInstance : nsISupports
{
    /////////////////////////////////////////////////////////////////////
    // Plugin Status Interface
    
    // Read-Only: Contains completion status of last operation
    attribute boolean Success;

    // Read-Only: Contains the current state of the scanner (IDLE|BUSY)
    attribute string State;

    /////////////////////////////////////////////////////////////////////
    // Image Preview Interface

    // Move zoom box to a given geometry in one step
    void ZoomImage(in unsigned short x, in unsigned short y, 
                   in unsigned short width, in unsigned short height);
    void ZoomImageWithAttributes(in unsigned short x, 
                                 in unsigned short y, 
                                 in unsigned short width, 
                                 in unsigned short height,
                                 in long req_line_width, 
                                 in string req_line_style,
                                 in string req_cap_style, 
                                 in string req_join_style);

    // Undo all croping and reset zoom box for entire image
    void Restore ();

    // Zoom in on the image and reset the zoom box to contain 
    // the entire image.
    void Crop(in unsigned short x, in unsigned short y,
              in unsigned short width, in unsigned short height);

    // Read/Write zoom box geometry
    // (Each write will trigger a refresh!)
    attribute unsigned short ZoomX;
    attribute unsigned short ZoomY;
    attribute unsigned short ZoomWidth;
    attribute unsigned short ZoomHeight;

    // Read/Write zoom box line attributes
    // (Each write will trigger a refresh!)
    attribute long   ZoomLineWidth;
    attribute string ZoomLineStyle;
    attribute string ZoomCapStyle;
    attribute string ZoomJoinStyle;

    // Read-Only zoom box change indicators
    // (For SANE devices that support changing the scan area,
    //  this allows for the controling JavaScript to safely adjust
    //  the scan area in a device specific manner.)
    attribute float ZoomBR_XChange;  // % bottom right x change on last zoom
    attribute float ZoomBR_YChange;  // % bottom right y ...
    attribute float ZoomTL_XChange;  // % top left x ...
    attribute float ZoomTL_YChange;  // % top left y ...

    // Read/Write JPEG compression attributes
    attribute long Quality;
    attribute string Method;

    //////////////////////////////////////////////////////////////////////
    // Generic SANE Interface

    // READ_ONLY: returns a colon delimited list of option descriptions
    //            where each option description is a comma delimited
    //            list of values
    attribute string DeviceOptions;

    // Returns or sets the active device.
    attribute string ActiveDevice;

    // READ_ONLY: returns a comma delimited list of image parameters
    attribute string ImageParameters;

    // READ_ONLY: returns a comma delimited list of available devices
    attribute string AvailableDevices;

    // Pull image from device with current option settings.
    // As a side effect, the zoom box is set to contain the
    // entire image.
    void ScanImage();
    void SetOption(in string name, in string value);

    // Pop up a dialog to save current image to a file
    void SaveImage();
 };

%{ C++
//10982800-365e-11d3-a2bf-0004ac780ef3
#define NS_SANE_PLUGIN_CONTROL_CID \
 { 0x10982800, 0x365e, 0x11d3, { 0xa2, 0xbf, 0x0, 0x04, 0xac, 0x78, 0x0e, 0xf3 }}

%}