dom/chrome-webidl/XULPopupElement.webidl

   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 };