layout/xul/nsIPopupBoxObject.idl

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