dom/webidl/XULPopupElement.webidl

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