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