/*
 * BEGIN FLOCK GPL
 *
 * Copyright Flock Inc. 2005-2009
 * 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 "nsIDOMHTMLElement.idl"


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


[scriptable, uuid(3bf74fbf-2068-4a70-8df6-61526cf8f85d)]
interface flockIRichDNDService : nsISupports {
  /**
   * Adds the given content to the target element in a rich text editor.
   *
   * @param aContent (in) the content to be added
   * @param aTargetElement (in) the target on which we are dropping rich content
   */
  void addToRichTextEditor(in AString aContent,
                           in nsIDOMHTMLElement aTargetElement);

  /**
   * 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);

  /**
   * Returns TRUE if the given element contains a breadcrumb.
   *
   * @param aElement (in) the element to inspect for breadcrumb 
   */
  boolean hasBreadcrumb(in nsIDOMHTMLElement aElement);

  /**
   * 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; else FALSE.
   */
  boolean handleDrop(in nsIDragSession aSession,
                     in nsIDOMHTMLElement aTargetElement);

  /**
   * Checks if the element is within a rich text editor
   *
   * @param aElement (in) the element to check
   * @return TRUE if the element is within a rich text editor; else FALSE.
   */
  boolean isInRichTextEditor(in nsIDOMHTMLElement aElement);

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

[scriptable, uuid(a365b092-97bf-43ca-ab7d-1c713fc8f5f8)]
interface flockIRichContentDropHandler : nsISupports {
  /**
   * Handle the rich content drop
   *
   * @param aFlavours (in) use to determine type of content
   * @param aTargetElement (in) the target on which we are dropping rich content
   * @return TRUE if the component handled the drop; else FALSE.
   */
  boolean handleDrop(in nsITransferable aFlavours,
                     in nsIDOMHTMLElement aTargetElement);
};
