1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/layout/xul/nsIPopupBoxObject.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,183 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIDOMElement;
1.12 +interface nsIDOMNode;
1.13 +interface nsIDOMEvent;
1.14 +interface nsIDOMClientRect;
1.15 +
1.16 +[scriptable, uuid(b1192cac-467b-42ca-88d6-fcdec5bb4ef7)]
1.17 +interface nsIPopupBoxObject : nsISupports
1.18 +{
1.19 + /**
1.20 + * This method is deprecated. Use openPopup or openPopupAtScreen instead.
1.21 + */
1.22 + void showPopup(in nsIDOMElement srcContent, in nsIDOMElement popupContent,
1.23 + in long xpos, in long ypos,
1.24 + in wstring popupType, in wstring anchorAlignment,
1.25 + in wstring popupAlignment);
1.26 +
1.27 + /**
1.28 + * Hide the popup if it is open.
1.29 + */
1.30 + void hidePopup();
1.31 +
1.32 + /**
1.33 + * Allow the popup to automatically position itself.
1.34 + */
1.35 + attribute boolean autoPosition;
1.36 +
1.37 + /**
1.38 + * If keyboard navigation is enabled, the keyboard may be used to navigate
1.39 + * the menuitems on the popup. Enabling keyboard navigation is the default
1.40 + * behaviour and will install capturing key event listeners on the popup
1.41 + * that do not propagate key events to the contents. If you wish to place
1.42 + * elements in a popup which accept key events, such as textboxes, keyboard
1.43 + * navigation should be disabled.
1.44 + *
1.45 + * Setting ignorekeys="true" on the popup element also disables keyboard
1.46 + * navigation, and is recommended over calling this method.
1.47 + */
1.48 + void enableKeyboardNavigator(in boolean enableKeyboardNavigator);
1.49 +
1.50 + /**
1.51 + * Enable automatic popup dismissal. This only has effect when called
1.52 + * on an open popup.
1.53 + */
1.54 + void enableRollup(in boolean enableRollup);
1.55 +
1.56 + /**
1.57 + * Control whether the event that caused the popup to be automatically
1.58 + * dismissed ("rolled up") should be consumed, or dispatched as a
1.59 + * normal event. This should be set immediately before calling showPopup()
1.60 + * if non-default behavior is desired.
1.61 + */
1.62 + const uint32_t ROLLUP_DEFAULT = 0; /* widget/platform default */
1.63 + const uint32_t ROLLUP_CONSUME = 1; /* consume the rollup event */
1.64 + const uint32_t ROLLUP_NO_CONSUME = 2; /* don't consume the rollup event */
1.65 + void setConsumeRollupEvent(in uint32_t consume);
1.66 +
1.67 + /**
1.68 + * Size the popup to the given dimensions
1.69 + */
1.70 + void sizeTo(in long width, in long height);
1.71 +
1.72 + /**
1.73 + * Move the popup to a point on screen in CSS pixels.
1.74 + */
1.75 + void moveTo(in long left, in long top);
1.76 +
1.77 + /**
1.78 + * Open the popup relative to a specified node at a specific location.
1.79 + *
1.80 + * The popup may be either anchored to another node or opened freely.
1.81 + * To anchor a popup to a node, supply an anchor node and set the position
1.82 + * to a string indicating the manner in which the popup should be anchored.
1.83 + * Possible values for position are:
1.84 + * before_start, before_end, after_start, after_end,
1.85 + * start_before, start_after, end_before, end_after,
1.86 + * overlap, after_pointer
1.87 + *
1.88 + * The anchor node does not need to be in the same document as the popup.
1.89 + *
1.90 + * If the attributesOverride argument is true, the popupanchor, popupalign
1.91 + * and position attributes on the popup node override the position value
1.92 + * argument. If attributesOverride is false, the attributes are only used
1.93 + * if position is empty.
1.94 + *
1.95 + * For an anchored popup, the x and y arguments may be used to offset the
1.96 + * popup from its anchored position by some distance, measured in CSS pixels.
1.97 + * x increases to the right and y increases down. Negative values may also
1.98 + * be used to move to the left and upwards respectively.
1.99 + *
1.100 + * Unanchored popups may be created by supplying null as the anchor node.
1.101 + * An unanchored popup appears at the position specified by x and y,
1.102 + * relative to the viewport of the document containing the popup node. In
1.103 + * this case, position and attributesOverride are ignored.
1.104 + *
1.105 + * @param anchorElement the node to anchor the popup to, may be null
1.106 + * @param position manner is which to anchor the popup to node
1.107 + * @param x horizontal offset
1.108 + * @param y vertical offset
1.109 + * @param isContextMenu true for context menus, false for other popups
1.110 + * @param attributesOverride true if popup node attributes override position
1.111 + * @param triggerEvent the event that triggered this popup (mouse click for example)
1.112 + */
1.113 + void openPopup(in nsIDOMElement anchorElement,
1.114 + in AString position,
1.115 + in long x, in long y,
1.116 + in boolean isContextMenu,
1.117 + in boolean attributesOverride,
1.118 + in nsIDOMEvent triggerEvent);
1.119 +
1.120 + /**
1.121 + * Open the popup at a specific screen position specified by x and y. This
1.122 + * position may be adjusted if it would cause the popup to be off of the
1.123 + * screen. The x and y coordinates are measured in CSS pixels, and like all
1.124 + * screen coordinates, are given relative to the top left of the primary
1.125 + * screen.
1.126 + *
1.127 + * @param isContextMenu true for context menus, false for other popups
1.128 + * @param x horizontal screen position
1.129 + * @param y vertical screen position
1.130 + * @param triggerEvent the event that triggered this popup (mouse click for example)
1.131 + */
1.132 + void openPopupAtScreen(in long x, in long y,
1.133 + in boolean isContextMenu,
1.134 + in nsIDOMEvent triggerEvent);
1.135 +
1.136 + /**
1.137 + * Returns the state of the popup:
1.138 + * closed - the popup is closed
1.139 + * open - the popup is open
1.140 + * showing - the popup is in the process of being shown
1.141 + * hiding - the popup is in the process of being hidden
1.142 + */
1.143 + readonly attribute AString popupState;
1.144 +
1.145 + /**
1.146 + * The node that triggered the popup. If the popup is not open, will return
1.147 + * null.
1.148 + */
1.149 + readonly attribute nsIDOMNode triggerNode;
1.150 +
1.151 + /**
1.152 + * Retrieve the anchor that was specified to openPopup or for menupopups in a
1.153 + * menu, the parent menu.
1.154 + */
1.155 + readonly attribute nsIDOMElement anchorNode;
1.156 +
1.157 + /**
1.158 + * Retrieve the screen rectangle of the popup, including the area occupied by
1.159 + * any titlebar or borders present.
1.160 + */
1.161 + nsIDOMClientRect getOuterScreenRect();
1.162 +
1.163 + /**
1.164 + * Move an open popup to the given anchor position. The arguments have the same
1.165 + * meaning as the corresponding argument to openPopup. This method has no effect
1.166 + * on popups that are not open.
1.167 + */
1.168 + void moveToAnchor(in nsIDOMElement anchorElement,
1.169 + in AString position,
1.170 + in long x, in long y,
1.171 + in boolean attributesOverride);
1.172 +
1.173 + /** Returns the alignment position where the popup has appeared relative to its
1.174 + * anchor node or point, accounting for any flipping that occurred.
1.175 + */
1.176 + readonly attribute AString alignmentPosition;
1.177 + readonly attribute long alignmentOffset;
1.178 +};
1.179 +
1.180 +%{C++
1.181 +class nsIBoxObject;
1.182 +
1.183 +nsresult
1.184 +NS_NewPopupBoxObject(nsIBoxObject** aResult);
1.185 +
1.186 +%}
