XULPopupElement.webidl (7974B)
1 /* -*- Mode: IDL; 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/. */ 5 6 dictionary OpenPopupOptions { 7 // manner in which to anchor the popup to node 8 DOMString position = ""; 9 // horizontal offset 10 long x = 0; 11 // vertical offset 12 long y = 0; 13 // isContextMenu true for context menus, false for other popups 14 boolean isContextMenu = false; 15 // true if popup node attributes override position 16 boolean attributesOverride = false; 17 // triggerEvent the event that triggered this popup (mouse click for example) 18 Event? triggerEvent = null; 19 }; 20 21 dictionary ActivateMenuItemOptions { 22 boolean altKey = false; 23 boolean metaKey = false; 24 boolean ctrlKey = false; 25 boolean shiftKey = false; 26 short button = 0; 27 }; 28 29 typedef (DOMString or OpenPopupOptions) StringOrOpenPopupOptions; 30 31 [ChromeOnly, 32 Exposed=Window] 33 interface XULPopupElement : XULElement 34 { 35 [HTMLConstructor] constructor(); 36 37 /** 38 * Open the popup relative to a specified node at a specific location. 39 * 40 * If the popup is already open, calling this method has no effect. 41 * 42 * The popup may be either anchored to another node or opened freely. 43 * To anchor a popup to a node, supply an anchor node and set the position 44 * to a string indicating the manner in which the popup should be anchored. 45 * Possible values for position are: 46 * before_start, before_end, after_start, after_end, 47 * start_before, start_after, end_before, end_after, 48 * overlap, after_pointer 49 * 50 * The anchor node does not need to be in the same document as the popup. 51 * 52 * If the attributesOverride argument is true, the popupanchor, popupalign 53 * and position attributes on the popup node override the position value 54 * argument. If attributesOverride is false, the attributes are only used 55 * if position is empty. 56 * 57 * For an anchored popup, the x and y arguments may be used to offset the 58 * popup from its anchored position by some distance, measured in CSS pixels. 59 * x increases to the right and y increases down. Negative values may also 60 * be used to move to the left and upwards respectively. 61 * 62 * Unanchored popups may be created by supplying null as the anchor node. 63 * An unanchored popup appears at the position specified by x and y, 64 * relative to the viewport of the document containing the popup node. In 65 * this case, position and attributesOverride are ignored. 66 * 67 * @param anchorElement the node to anchor the popup to, may be null 68 * @param options either options to use, or a string position 69 * @param x horizontal offset 70 * @param y vertical offset 71 * @param isContextMenu true for context menus, false for other popups 72 * @param attributesOverride true if popup node attributes override position 73 * @param triggerEvent the event that triggered this popup (mouse click for example) 74 */ 75 undefined openPopup(optional Element? anchorElement = null, 76 optional StringOrOpenPopupOptions options = {}, 77 optional long x = 0, 78 optional long y = 0, 79 optional boolean isContextMenu = false, 80 optional boolean attributesOverride = false, 81 optional Event? triggerEvent = null); 82 83 /** 84 * Open the popup at a specific screen position specified by x and y. This 85 * position may be adjusted if it would cause the popup to be off of the 86 * screen. The x and y coordinates are measured in CSS pixels, and like all 87 * screen coordinates, are given relative to the top left of the primary 88 * screen. 89 * 90 * @param isContextMenu true for context menus, false for other popups 91 * @param x horizontal screen position 92 * @param y vertical screen position 93 * @param triggerEvent the event that triggered this popup (mouse click for example) 94 */ 95 undefined openPopupAtScreen(optional long x = 0, optional long y = 0, 96 optional boolean isContextMenu = false, 97 optional Event? triggerEvent = null); 98 99 /** 100 * Open the popup anchored at a specific screen rectangle. This function is 101 * similar to openPopup except that that rectangle of the anchor is supplied 102 * rather than an element. The anchor rectangle arguments are screen 103 * coordinates. 104 * 105 * If the popup is already open, calling this method has no effect. 106 */ 107 undefined openPopupAtScreenRect(optional DOMString position = "", 108 optional long x = 0, 109 optional long y = 0, 110 optional long width = 0, 111 optional long height = 0, 112 optional boolean isContextMenu = false, 113 optional boolean attributesOverride = false, 114 optional Event? triggerEvent = null); 115 116 /** 117 * Hide the popup if it is open. The cancel argument is used as a hint that 118 * the popup is being closed because it has been cancelled, rather than 119 * something being selected within the panel. 120 * 121 * @param cancel if true, then the popup is being cancelled. 122 */ 123 undefined hidePopup(optional boolean cancel = false); 124 125 /** 126 * Activate the item itemElement. This is the recommended way to "click" a 127 * menuitem in automated tests that involve menus. 128 * Fires the command event for the item and then closes the menu. 129 * 130 * Throws an InvalidStateError if the menu is not currently open, or if the 131 * menuitem is not inside this menu, or if the menuitem is hidden. The menuitem 132 * may be an item in a submenu, but that submenu must be open. 133 * 134 * @param itemElement The menuitem to activate. 135 * @param options Which modifier keys and button should be set on the command 136 * event. 137 */ 138 [Throws] 139 undefined activateItem(Element itemElement, 140 optional ActivateMenuItemOptions options = {}); 141 142 /** 143 * Attribute getter and setter for label. 144 */ 145 [SetterThrows] 146 attribute DOMString label; 147 148 /** 149 * Attribute getter and setter for position. 150 */ 151 [SetterThrows] 152 attribute DOMString position; 153 154 /** 155 * Returns the state of the popup: 156 * closed - the popup is closed 157 * open - the popup is open 158 * showing - the popup is in the process of being shown 159 * hiding - the popup is in the process of being hidden 160 */ 161 readonly attribute DOMString state; 162 163 /** 164 * The node that triggered the popup. If the popup is not open, will return 165 * null. 166 */ 167 readonly attribute Node? triggerNode; 168 169 /** 170 * Retrieve the anchor that was specified to openPopup or for menupopups in a 171 * menu, the parent menu. 172 */ 173 readonly attribute Element? anchorNode; 174 175 /** 176 * Retrieve the screen rectangle of the popup, including the area occupied by 177 * any titlebar or borders present. 178 */ 179 DOMRect getOuterScreenRect(); 180 181 /** 182 * Move the popup to a point on screen in CSS pixels. 183 */ 184 undefined moveTo(long left, long top); 185 186 /** 187 * Move an open popup to the given anchor position. The arguments have the same 188 * meaning as the corresponding argument to openPopup. This method has no effect 189 * on popups that are not open. 190 */ 191 undefined moveToAnchor(optional Element? anchorElement = null, 192 optional DOMString position = "", 193 optional long x = 0, optional long y = 0, 194 optional boolean attributesOverride = false); 195 196 /** 197 * Size the popup to the given dimensions 198 */ 199 undefined sizeTo(long width, long height); 200 201 undefined setConstraintRect(DOMRectReadOnly rect); 202 203 readonly attribute boolean isWaylandDragSource; 204 readonly attribute boolean isWaylandPopup; 205 };