/* ***** 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 Komodo code.
 * 
 * The Initial Developer of the Original Code is ActiveState Software Inc.
 * Portions created by ActiveState Software Inc are Copyright (C) 2000-2007
 * ActiveState Software Inc. All Rights Reserved.
 * 
 * Contributor(s):
 *   ActiveState Software Inc
 * 
 * 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 ***** */

#include "nsISupports.idl"

/**
 * Synchronous color picker interface
 * @deprecated since Komodo 7.0b1 - This launches UI; being synchronus means if
 *      the user goes away for a bit the app will think it has hung.  It can
 *      also introduce bad reentrancy hazards, see bug 91299.  Use
 *      koIColorPickerAsync instead.
 */
[scriptable, deprecated, uuid(4e03a4be-ab01-4ce1-bc8a-104130d558a7)]
interface koIColorPicker : nsISupports {
        /**
         * Open the color picker dialog with the startingcolor.
         * @param startingcolor - Color string, must use the format "#ABCDEF".
         */
    [deprecated] string pickColor(in string startingcolor);
        /**
         * Open the color picker dialog with the startingcolor at position x,y.
         * @param startingcolor - Color string, must use the format "#ABCDEF".
         * @param screenX - the X screen position to open the dialog at.
         * @param screenY - the Y screen position to open the dialog at.
         */
    [deprecated] string pickColorWithPositioning(in string startingcolor,
                                                 in long screenX,
                                                 in long screenY);
};

/**
 * Color picker callback interface
 */
[scriptable, function, uuid(3120484a-2255-46be-8c8f-267042940233)]
interface koIColorPickerAsyncCallback : nsISupports {
    /**
     * Callback for the color picker.
     * @param aColor the resulting color, as a hexidecimal string of the form
     *      #rrggbb.  For example, #000000 is black, and #ff00ff is magenta.
     *      If the user cancelled or an error occurred, this is instead a void
     *      string (in JavaScript, null).
     * @param aAlpha the resulting alpha value, as a double between 0.0 and 1.0
     *      inclusive.
     */
    void handleResult(in ACString aColor, in double aAlpha);
};

/**
 * Color picker interface
 */
[scriptable, uuid(1fcc26be-8db2-48b2-9a67-fc95b0b4712e)]
interface koIColorPickerAsync : nsISupports {
    /**
     * Open the color picker dialog.
     * @param aCallback - The callback to invoke when a color has been picked
     *      (or if the user has cancelled the dialog).
     * @param aStartingColor - The initial colour the picker has selected; must
     *      be a hexidecimal string of the form #rrggbb.  For example, #00ffff
     *      is cyan, and #00ff00 is bright green.  Must not be null.
     * @param aStartingAlpha - The alpha value of the starting color.
     * @param aScreenX - The X screen position to open the dialog at.
     * @param aScreenY - The Y screen position to open the dialog at.
     * @note this may actually be implemented synchronusly depending on platform
     * @note If the color picker does _not_ support selecting alpha values, then
     *      it should attempt to maintain the input alpha.
     * @note If aScreenX and aScreenY are both zero, the picker position is at
     *      the descretion of the dialog.
     * @note Not all color pickers implement positioning support.
     */
    void pickColorAsync(in koIColorPickerAsyncCallback aCallback,
                        in ACString aStartingColor,
                        in double aStartingAlpha,
                        [optional] in long aScreenX,
                        [optional] in long aScreenY);
};
