layout/xul/nsIPopupBoxObject.idl@7e26c7da4463
layout/xul/nsIPopupBoxObject.idl
Wed, 31 Dec 2014 06:55:50 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:55:50 +0100
- changeset 2
- 7e26c7da4463
- permissions
- -rw-r--r--
Added tag UPSTREAM_283F7C6 for changeset ca08bd8f51b2
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include "nsISupports.idl"
8 interface nsIDOMElement;
9 interface nsIDOMNode;
10 interface nsIDOMEvent;
11 interface nsIDOMClientRect;
13 [scriptable, uuid(b1192cac-467b-42ca-88d6-fcdec5bb4ef7)]
14 interface nsIPopupBoxObject : nsISupports
15 {
16 /**
17 * This method is deprecated. Use openPopup or openPopupAtScreen instead.
18 */
19 void showPopup(in nsIDOMElement srcContent, in nsIDOMElement popupContent,
20 in long xpos, in long ypos,
21 in wstring popupType, in wstring anchorAlignment,
22 in wstring popupAlignment);
24 /**
25 * Hide the popup if it is open.
26 */
27 void hidePopup();
29 /**
30 * Allow the popup to automatically position itself.
31 */
32 attribute boolean autoPosition;
34 /**
35 * If keyboard navigation is enabled, the keyboard may be used to navigate
36 * the menuitems on the popup. Enabling keyboard navigation is the default
37 * behaviour and will install capturing key event listeners on the popup
38 * that do not propagate key events to the contents. If you wish to place
39 * elements in a popup which accept key events, such as textboxes, keyboard
40 * navigation should be disabled.
41 *
42 * Setting ignorekeys="true" on the popup element also disables keyboard
43 * navigation, and is recommended over calling this method.
44 */
45 void enableKeyboardNavigator(in boolean enableKeyboardNavigator);
47 /**
48 * Enable automatic popup dismissal. This only has effect when called
49 * on an open popup.
50 */
51 void enableRollup(in boolean enableRollup);
53 /**
54 * Control whether the event that caused the popup to be automatically
55 * dismissed ("rolled up") should be consumed, or dispatched as a
56 * normal event. This should be set immediately before calling showPopup()
57 * if non-default behavior is desired.
58 */
59 const uint32_t ROLLUP_DEFAULT = 0; /* widget/platform default */
60 const uint32_t ROLLUP_CONSUME = 1; /* consume the rollup event */
61 const uint32_t ROLLUP_NO_CONSUME = 2; /* don't consume the rollup event */
62 void setConsumeRollupEvent(in uint32_t consume);
64 /**
65 * Size the popup to the given dimensions
66 */
67 void sizeTo(in long width, in long height);
69 /**
70 * Move the popup to a point on screen in CSS pixels.
71 */
72 void moveTo(in long left, in long top);
74 /**
75 * Open the popup relative to a specified node at a specific location.
76 *
77 * The popup may be either anchored to another node or opened freely.
78 * To anchor a popup to a node, supply an anchor node and set the position
79 * to a string indicating the manner in which the popup should be anchored.
80 * Possible values for position are:
81 * before_start, before_end, after_start, after_end,
82 * start_before, start_after, end_before, end_after,
83 * overlap, after_pointer
84 *
85 * The anchor node does not need to be in the same document as the popup.
86 *
87 * If the attributesOverride argument is true, the popupanchor, popupalign
88 * and position attributes on the popup node override the position value
89 * argument. If attributesOverride is false, the attributes are only used
90 * if position is empty.
91 *
92 * For an anchored popup, the x and y arguments may be used to offset the
93 * popup from its anchored position by some distance, measured in CSS pixels.
94 * x increases to the right and y increases down. Negative values may also
95 * be used to move to the left and upwards respectively.
96 *
97 * Unanchored popups may be created by supplying null as the anchor node.
98 * An unanchored popup appears at the position specified by x and y,
99 * relative to the viewport of the document containing the popup node. In
100 * this case, position and attributesOverride are ignored.
101 *
102 * @param anchorElement the node to anchor the popup to, may be null
103 * @param position manner is which to anchor the popup to node
104 * @param x horizontal offset
105 * @param y vertical offset
106 * @param isContextMenu true for context menus, false for other popups
107 * @param attributesOverride true if popup node attributes override position
108 * @param triggerEvent the event that triggered this popup (mouse click for example)
109 */
110 void openPopup(in nsIDOMElement anchorElement,
111 in AString position,
112 in long x, in long y,
113 in boolean isContextMenu,
114 in boolean attributesOverride,
115 in nsIDOMEvent triggerEvent);
117 /**
118 * Open the popup at a specific screen position specified by x and y. This
119 * position may be adjusted if it would cause the popup to be off of the
120 * screen. The x and y coordinates are measured in CSS pixels, and like all
121 * screen coordinates, are given relative to the top left of the primary
122 * screen.
123 *
124 * @param isContextMenu true for context menus, false for other popups
125 * @param x horizontal screen position
126 * @param y vertical screen position
127 * @param triggerEvent the event that triggered this popup (mouse click for example)
128 */
129 void openPopupAtScreen(in long x, in long y,
130 in boolean isContextMenu,
131 in nsIDOMEvent triggerEvent);
133 /**
134 * Returns the state of the popup:
135 * closed - the popup is closed
136 * open - the popup is open
137 * showing - the popup is in the process of being shown
138 * hiding - the popup is in the process of being hidden
139 */
140 readonly attribute AString popupState;
142 /**
143 * The node that triggered the popup. If the popup is not open, will return
144 * null.
145 */
146 readonly attribute nsIDOMNode triggerNode;
148 /**
149 * Retrieve the anchor that was specified to openPopup or for menupopups in a
150 * menu, the parent menu.
151 */
152 readonly attribute nsIDOMElement anchorNode;
154 /**
155 * Retrieve the screen rectangle of the popup, including the area occupied by
156 * any titlebar or borders present.
157 */
158 nsIDOMClientRect getOuterScreenRect();
160 /**
161 * Move an open popup to the given anchor position. The arguments have the same
162 * meaning as the corresponding argument to openPopup. This method has no effect
163 * on popups that are not open.
164 */
165 void moveToAnchor(in nsIDOMElement anchorElement,
166 in AString position,
167 in long x, in long y,
168 in boolean attributesOverride);
170 /** Returns the alignment position where the popup has appeared relative to its
171 * anchor node or point, accounting for any flipping that occurred.
172 */
173 readonly attribute AString alignmentPosition;
174 readonly attribute long alignmentOffset;
175 };
177 %{C++
178 class nsIBoxObject;
180 nsresult
181 NS_NewPopupBoxObject(nsIBoxObject** aResult);
183 %}
