/*
 * BEGIN FLOCK GPL
 *
 * Copyright Flock Inc. 2005-2008
 * http://flock.com
 *
 * This file may be used under the terms of the
 * GNU General Public License Version 2 or later (the "GPL"),
 * http://www.gnu.org/licenses/gpl.html
 *
 * 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.
 *
 * END FLOCK GPL
 */

#include "nsISupports.idl"
#include "nsITransferable.idl"
#include "nsIDragSession.idl"
#include "nsIDOMHTMLTextAreaElement.idl"


/**
 * Interface for passing messages ready to be posted or shared via a service
 */
[scriptable, uuid(A6204395-AB6E-43F0-8BED-29AFD826B1E8)]
interface flockIMessage : nsISupports {
  attribute AString subject;
  attribute AString body;
  attribute AString htmlbody;
};


[scriptable, uuid(584980d2-5d07-42aa-9916-cd404d80e424)]
interface flockIRichDNDService: nsISupports {
  /**
   * Produce a rich nsITransferable from a nsIDragSession. The result
   * is different from what you would get from nsIDragSession.getData(),
   * because we analyse the sourceNode to enrich the resulting
   * nsITransferable. Additional data from the drop may be included to provide
   * more information to the transferable.
   *
   * @param aSession (in) the current drag session
   * @param aDropFlavour (in) the flavour of the drop data
   * @param aDropData (in) the value of the drop data
   * @return a nsITransferable with one or more of the following flavors:
   *         - text/unicode
   *         - text/html
   *         - text/x-moz-url
   *         - text/x-flock-media
   *         - text/x-flock-textcitation
   *         - text/x-flock-htmlcitation
   *
   * text/x-flock-media has the same syntax as text/x-moz-url:
   *    url + "\n" + title
   * we use it to make a distinction with url pointing to webpages, so
   * the caller can treat media data in a different way
   *
   * text/x-flock-{text/html}citation are a represenation of the data
   * plus its source (with title and URL of the source page)
   */
  nsITransferable getRichSelection(in nsIDragSession aSession,
                                   in AString aDropFlavour,
                                   in AString aDropData);

  /**
   * Helper method to extract a flockIMessage from an nsITransferable subject
   * Supports several flavours of transferable data:
   *         - text/unicode
   *         - text/html
   *         - text/x-moz-url
   *         - text/x-flock-media
   *         - text/x-flock-textcitation
   *         - text/x-flock-htmlcitation
   *         - moz/rdfitem
   *
   * @param aSubject (in) a nsITransferable
   * @param aListSize (in) the number of elements in the flavor list array
   * @param aFlavorList (in) an array of desired flavors, in order of
   *                         preference. The message is formatted based on the
   *                         first flavor from the list that is supported by the
   *                         transferable. If none are found, it looks for a
   *                         supported flavor in the transferable.
   * @return a flockIMessage object.
   */
  flockIMessage getMessageFromTransferable(in nsITransferable aSubject,
                                           in unsigned long aListSize,
                                           [array, size_is(aListSize)]in string aFlavorList);

  /**
   * Returns appropriately formatted breadcrumb.
   *
   * @param aType (in) [optional] one of the following:
   *        - plain (default)
   *        - rich
   */
  AString getBreadcrumb(in AString aType);

  /**
   * Checks if the selection contains rich video content
   *
   * @param aSession (in) the current drag session
   * @return true if the selection contains rich video content
   */
  boolean isSelectionRichVideoContent(in nsIDragSession aSession);

  /**
   * Determine the appropriate supported service to handle the rich content drop
   * to an element on the page.
   *
   * @param aSession (in) the drag and drop session
   * @param aTargetElement (in) the target on which we are dropping rich content
   * @return true if the drop was handled
   */
  boolean handleDrop(in nsIDragSession aSession,
                     in nsIDOMHTMLElement aTargetElement);
};

[scriptable, uuid(a04edae3-b463-4402-9ce0-c8e72fa9efd4)]
interface flockIRichContentDropHandler: nsISupports {
  /**
   * Handle the rich content drop
   * 
   * @param aFlavours (in) use to determine type of content
   * @param aTextarea (in) the TEXTAREA target we are dropping rich content on
   * @return true if the supported service handled the drop
   */
  boolean handleDrop(in nsITransferable aFlavours,
                     in nsIDOMHTMLTextAreaElement aTextarea);
};
