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