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