dom/webidl/Selection.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 file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  *
   6  * The origin of this IDL file is
   7  * https://w3c.github.io/selection-api/#selection-interface
   8  *
   9  * Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C
  10  * liability, trademark and document use rules apply.
  11  */
  12
  13 [Exposed=Window]
  14 interface Selection {
  15   [NeedsCallerType]
  16   readonly attribute Node?         anchorNode;
  17   [NeedsCallerType]
  18   readonly attribute unsigned long anchorOffset;
  19   [NeedsCallerType]
  20   readonly attribute Node?         focusNode;
  21   [NeedsCallerType]
  22   readonly attribute unsigned long focusOffset;
  23   readonly attribute boolean       isCollapsed;
  24   [ChromeOnly]
  25   readonly attribute boolean       areNormalAndCrossShadowBoundaryRangesCollapsed;
  26   /**
  27    * Returns the number of ranges in the selection.
  28    */
  29   readonly attribute unsigned long rangeCount;
  30   readonly attribute DOMString     type;
  31   readonly attribute DOMString direction;
  32   /**
  33    * Returns the range at the specified index.  Throws if the index is
  34    * out of range.
  35    */
  36   [Throws]
  37   Range     getRangeAt(unsigned long index);
  38   /**
  39    * Adds a range to the current selection.
  40    */
  41   [Throws, BinaryName="addRangeJS"]
  42   undefined addRange(Range range);
  43   /**
  44    * Removes a range from the current selection.
  45    */
  46   [Throws, BinaryName="removeRangeAndUnselectFramesAndNotifyListeners"]
  47   undefined removeRange(Range range);
  48   /**
  49    * Removes all ranges from the current selection.
  50    */
  51   [Throws]
  52   undefined removeAllRanges();
  53   [Throws, BinaryName="RemoveAllRanges"]
  54   undefined empty();
  55
  56   [Pref="dom.shadowdom.selection_across_boundary_enabled"]
  57   sequence<StaticRange> getComposedRanges(ShadowRoot... shadowRoots);
  58
  59   [Throws, BinaryName="collapseJS"]
  60   undefined collapse(Node? node, optional unsigned long offset = 0);
  61   [Throws, BinaryName="collapseJS"]
  62   undefined setPosition(Node? node, optional unsigned long offset = 0);
  63   [Throws, BinaryName="collapseToStartJS"]
  64   undefined collapseToStart();
  65   [Throws, BinaryName="collapseToEndJS"]
  66   undefined collapseToEnd();
  67   [Throws, BinaryName="extendJS"]
  68   undefined extend(Node node, optional unsigned long offset = 0);
  69   [Throws, BinaryName="setBaseAndExtentJS"]
  70   undefined setBaseAndExtent(Node anchorNode,
  71                              unsigned long anchorOffset,
  72                              Node focusNode,
  73                              unsigned long focusOffset);
  74   [Throws, BinaryName="selectAllChildrenJS"]
  75   undefined selectAllChildren(Node node);
  76   [CEReactions, Throws]
  77   undefined deleteFromDocument();
  78   [Throws]
  79   boolean   containsNode(Node node,
  80                          optional boolean allowPartialContainment = false);
  81   stringifier DOMString ();
  82 };
  83
  84 // Additional methods not currently in the spec
  85 partial interface Selection {
  86   [Throws]
  87   undefined modify(DOMString alter, DOMString direction,
  88                    DOMString granularity);
  89 };
  90
  91 // Additional chrome-only methods.
  92 interface nsISelectionListener;
  93 partial interface Selection {
  94   /**
  95    * A true value means "selection after newline"; false means "selection before
  96    * newline" when a selection is positioned "between lines".
  97    */
  98   [ChromeOnly,Throws, BinaryName=interlinePositionJS]
  99   attribute boolean interlinePosition;
 100
 101   [Throws]
 102   attribute short? caretBidiLevel;
 103
 104   [ChromeOnly,Throws]
 105   DOMString  toStringWithFormat(DOMString formatType, unsigned long flags, long wrapColumn);
 106   [ChromeOnly]
 107   undefined  addSelectionListener(nsISelectionListener newListener);
 108   [ChromeOnly]
 109   undefined  removeSelectionListener(nsISelectionListener listenerToRemove);
 110
 111   [ChromeOnly,BinaryName="rawType"]
 112   readonly attribute short selectionType;
 113
 114   /**
 115    * Return array of ranges intersecting with the given DOM interval.
 116    */
 117   [ChromeOnly,Throws,Pref="dom.testing.selection.GetRangesForInterval"]
 118   sequence<Range> GetRangesForInterval(Node beginNode, long beginOffset, Node endNode, long endOffset,
 119                                        boolean allowAdjacent);
 120
 121   /**
 122    * Scrolls a region of the selection, so that it is visible in
 123    * the scrolled view.
 124    *
 125    * @param aRegion the region inside the selection to scroll into view
 126    *                (see selection region constants defined in
 127    *                nsISelectionController).
 128    * @param aIsSynchronous when true, scrolls the selection into view
 129    *                       before returning. If false, posts a request which
 130    *                       is processed at some point after the method returns.
 131    * @param aVPercent how to align the frame vertically.
 132    * @param aHPercent how to align the frame horizontally.
 133    */
 134   [ChromeOnly,Throws]
 135   undefined scrollIntoView(short aRegion, boolean aIsSynchronous, short aVPercent, short aHPercent);
 136
 137   /**
 138    * setColors() sets custom colors for the selection.
 139    * Currently, this is supported only when the selection type is SELECTION_FIND.
 140    * Otherwise, throws an exception.
 141    *
 142    * @param aForegroundColor     The foreground color of the selection.
 143    *                             If this is "currentColor", foreground color
 144    *                             isn't changed by this selection.
 145    * @param aBackgroundColor     The background color of the selection.
 146    *                             If this is "transparent", background color is
 147    *                             never painted.
 148    * @param aAltForegroundColor  The alternative foreground color of the
 149    *                             selection.
 150    *                             If aBackgroundColor doesn't have sufficient
 151    *                             contrast with its around or foreground color
 152    *                             if "currentColor" is specified, alternative
 153    *                             colors are used if it have higher contrast.
 154    * @param aAltBackgroundColor  The alternative background color of the
 155    *                             selection.
 156    */
 157   [ChromeOnly,Throws]
 158   undefined setColors(DOMString aForegroundColor, DOMString aBackgroundColor,
 159                       DOMString aAltForegroundColor, DOMString aAltBackgroundColor);
 160
 161   /**
 162    * resetColors() forget the customized colors which were set by setColors().
 163    */
 164   [ChromeOnly]
 165   undefined resetColors();
 166 };