/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#include "nsISupports.idl"
interface nsIDOMEvent;
interface nsIDOMNode;
interface imgIContainer;
interface nsIURI;
interface nsIContextMenuInfo;
/* THIS IS A PUBLIC EMBEDDING API */
/**
* nsIContextMenuListener2
*
* This is an extended version of nsIContextMenuListener
* It provides a helper class, nsIContextMenuInfo, to allow access to
* background images as well as various utilities.
*
* @see nsIContextMenuListener
* @see nsIContextMenuInfo
*/
[scriptable, uuid(7fb719b3-d804-4964-9596-77cf924ee314)]
interface nsIContextMenuListener2 : nsISupports
{
/** Flag. No context. */
const unsigned long CONTEXT_NONE = 0;
/** Flag. Context is a link element. */
const unsigned long CONTEXT_LINK = 1;
/** Flag. Context is an image element. */
const unsigned long CONTEXT_IMAGE = 2;
/** Flag. Context is the whole document. */
const unsigned long CONTEXT_DOCUMENT = 4;
/** Flag. Context is a text area element. */
const unsigned long CONTEXT_TEXT = 8;
/** Flag. Context is an input element. */
const unsigned long CONTEXT_INPUT = 16;
/** Flag. Context is a background image. */
const unsigned long CONTEXT_BACKGROUND_IMAGE = 32;
/**
* Called when the browser receives a context menu event (e.g. user is right-mouse
* clicking somewhere on the document). The combination of flags, along with the
* attributes of <CODE>aUtils</CODE>, indicate where and what was clicked on.
*
* The following table describes what context flags and node combinations are
* possible.
*
* aContextFlags aUtils.targetNode
*
* CONTEXT_LINK <A>
* CONTEXT_IMAGE <IMG>
* CONTEXT_IMAGE | CONTEXT_LINK <IMG> with <A> as an ancestor
* CONTEXT_INPUT <INPUT>
* CONTEXT_INPUT | CONTEXT_IMAGE <INPUT> with type=image
* CONTEXT_TEXT <TEXTAREA>
* CONTEXT_DOCUMENT <HTML>
* CONTEXT_BACKGROUND_IMAGE <HTML> with background image
*
* @param aContextFlags Flags indicating the kind of context.
* @param aUtils Context information and helper utilities.
*
* @see nsIContextMenuInfo
*/
void onShowContextMenu(in unsigned long aContextFlags, in nsIContextMenuInfo aUtils);
};
/**
* nsIContextMenuInfo
*
* A helper object for implementors of nsIContextMenuListener2.
*/
[scriptable, uuid(2f977d56-5485-11d4-87e2-0010a4e75ef2)]
interface nsIContextMenuInfo : nsISupports
{
/**
* The DOM context menu event.
*/
readonly attribute nsIDOMEvent mouseEvent;
/**
* The DOM node most relevant to the context.
*/
readonly attribute nsIDOMNode targetNode;
/**
* Given the <CODE>CONTEXT_LINK</CODE> flag, <CODE>targetNode</CODE> may not
* nescesarily be a link. This returns the anchor from <CODE>targetNode</CODE>
* if it has one or that of its nearest ancestor if it does not.
*/
readonly attribute AString associatedLink;
/**
* Given the <CODE>CONTEXT_IMAGE</CODE> flag, these methods can be
* used in order to get the image for viewing, saving, or for the clipboard.
*
* @return <CODE>NS_OK</CODE> if successful, otherwise <CODE>NS_ERROR_FAILURE</CODE> if no
* image was found, or NS_ERROR_NULL_POINTER if an internal error occurs where we think there
* is an image, but for some reason it cannot be returned.
*/
readonly attribute imgIContainer imageContainer;
readonly attribute nsIURI imageSrc;
/**
* Given the <CODE>CONTEXT_BACKGROUND_IMAGE</CODE> flag, these methods can be
* used in order to get the image for viewing, saving, or for the clipboard.
*
* @return <CODE>NS_OK</CODE> if successful, otherwise <CODE>NS_ERROR_FAILURE</CODE> if no background
* image was found, or NS_ERROR_NULL_POINTER if an internal error occurs where we think there is a
* background image, but for some reason it cannot be returned.
*/
readonly attribute imgIContainer backgroundImageContainer;
readonly attribute nsIURI backgroundImageSrc;
};