nsISelectionController.idl (14123B)
1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ 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 7 #include "nsISelectionDisplay.idl" 8 9 %{C++ 10 using SelectionRegion = short; 11 12 namespace mozilla { 13 namespace dom { 14 class Selection; 15 } // namespace dom 16 17 struct ScrollAxis; 18 enum class ScrollFlags : uint8_t; 19 enum class SelectionScrollMode : uint8_t; 20 21 // RawSelectionType should be used to store nsISelectionController::SELECTION_*. 22 using RawSelectionType = short; 23 24 // SelectionTypeMask should be used to store bit-mask of selection types. 25 // The value can be retrieved with ToSelectionTypeMask() and checking if 26 // a selection type is in a mask with |SelectionType & SelectionTypeMask|. 27 using SelectionTypeMask = uint16_t; 28 29 // SelectionType should be used in internal handling because of type safe. 30 enum class SelectionType : RawSelectionType; 31 32 } // namespace mozilla 33 34 %} 35 36 interface nsIContent; 37 interface nsISelectionDisplay; 38 39 webidl Node; 40 webidl Selection; 41 42 [builtinclass, scriptable, uuid(3801c9d4-8e69-4bfc-9edb-b58278621f8f)] 43 interface nsISelectionController : nsISelectionDisplay 44 { 45 // Begin of RawSelectionType values. 46 const short SELECTION_NONE = 0; 47 // Corresponds to the Selection exposed via window.getSelection() and 48 // document.getSelection(). 49 const short SELECTION_NORMAL = 1; 50 // Corresponds to the Selection used for spellchecking in <textarea>s and 51 // "contentEditable" elements. 52 const short SELECTION_SPELLCHECK = 2; 53 const short SELECTION_IME_RAWINPUT = 3; 54 const short SELECTION_IME_SELECTEDRAWTEXT = 4; 55 const short SELECTION_IME_CONVERTEDTEXT = 5; 56 const short SELECTION_IME_SELECTEDCONVERTEDTEXT = 6; 57 // For accessibility API usage 58 const short SELECTION_ACCESSIBILITY = 7; 59 const short SELECTION_FIND = 8; 60 const short SELECTION_URLSECONDARY = 9; 61 const short SELECTION_URLSTRIKEOUT = 10; 62 const short SELECTION_TARGET_TEXT = 11; 63 // Custom Highlight API 64 // (see https://drafts.csswg.org/css-highlight-api-1/#enumdef-highlighttype) 65 const short SELECTION_HIGHLIGHT = 12; 66 // End of RawSelectionType values. 67 const short NUM_SELECTIONTYPES = 13; 68 69 // SelectionRegion values: 70 const short SELECTION_ANCHOR_REGION = 0; 71 const short SELECTION_FOCUS_REGION = 1; 72 const short SELECTION_WHOLE_SELECTION = 2; 73 const short NUM_SELECTION_REGIONS = 3; 74 75 const short SELECTION_OFF = 0; 76 const short SELECTION_HIDDEN =1;//>HIDDEN displays selection 77 const short SELECTION_ON = 2; 78 const short SELECTION_DISABLED = 3; 79 const short SELECTION_ATTENTION = 4; 80 81 /** 82 * SetDisplaySelection will set the display mode for the selection. OFF,ON,DISABLED 83 */ 84 void setDisplaySelection(in short toggle); 85 86 /** 87 * GetDisplaySelection will get the display mode for the selection. OFF,ON,DISABLED 88 */ 89 short getDisplaySelection(); 90 91 /** 92 * GetSelection will return the selection that the presentation 93 * shell may implement. 94 * 95 * @param aType This will hold the type of selection. This value must be one 96 * of RawSelectionType values. 97 * @param _return will hold the return value 98 */ 99 [binaryname(GetSelectionFromScript)] 100 Selection getSelection(in short type); 101 102 /** 103 * Return the selection object corresponding to a selection type. 104 */ 105 [noscript,nostdcall,notxpcom,binaryname(GetSelection)] 106 Selection getDOMSelection(in short aType); 107 108 /** 109 * Called when the selection controller should take the focus. 110 * 111 * This will take care to hide the previously-focused selection, show this 112 * selection, and repaint both. 113 */ 114 [noscript,nostdcall,notxpcom] 115 void selectionWillTakeFocus(); 116 117 /** 118 * Called when the selection controller has lost the focus. 119 * 120 * This will take care to hide and repaint the selection. 121 */ 122 [noscript,nostdcall,notxpcom] 123 void selectionWillLoseFocus(); 124 125 cenum ControllerScrollFlags : 8 { 126 // Scrolls the selection into view before returning. 127 SCROLL_SYNCHRONOUS = 1 << 1, 128 // Only the first ancestor will be scrolled into view. 129 // Note that this flushes layout, and thus can run script. 130 // See bug 418470 comment 12. 131 SCROLL_FIRST_ANCESTOR_ONLY = 1 << 2, 132 // Scrolls even if overflow is set to hidden. 133 SCROLL_OVERFLOW_HIDDEN = 1 << 3, 134 // No flag scrolls to nearest, vertically. 135 SCROLL_VERTICAL_NEAREST = 0, 136 SCROLL_VERTICAL_START = 1 << 4, 137 SCROLL_VERTICAL_CENTER = 1 << 5, 138 SCROLL_VERTICAL_END = 1 << 6, 139 }; 140 141 /** 142 * ScrollSelectionIntoView scrolls a region of the selection, 143 * so that it is visible in the scrolled view. 144 * 145 * @param aType the selection to scroll into view. This value must be one 146 * of RawSelectionType values. 147 * @param aRegion the region inside the selection to scroll into view. //SelectionRegion 148 * @param aFlags the scroll flags. 149 */ 150 [can_run_script] 151 void scrollSelectionIntoView(in short type, in short region, in nsISelectionController_ControllerScrollFlags flags); 152 153 /** 154 * RepaintSelection repaints the selection specified by aType. 155 * 156 * @param aType specifies the selection to repaint. 157 */ 158 void repaintSelection(in short type); 159 160 /** 161 * Set the caret as enabled or disabled. An enabled caret will 162 * draw or blink when made visible. A disabled caret will never show up. 163 * Can be called any time. 164 * @param aEnable true to enable caret. false to disable. 165 * @return always NS_OK 166 */ 167 void setCaretEnabled(in boolean enabled); 168 169 /** 170 * Set the caret readonly or not. An readonly caret will 171 * draw but not blink when made visible. 172 * @param aReadOnly true to enable caret. false to disable. 173 * @return always NS_OK 174 */ 175 void setCaretReadOnly(in boolean readOnly); 176 177 /** 178 * Gets the current state of the caret. 179 * @param aEnabled [OUT] set to the current caret state, as set by SetCaretEnabled 180 * @return if aOutEnabled==null, returns NS_ERROR_INVALID_ARG 181 * else NS_OK 182 */ 183 boolean getCaretEnabled(); 184 185 /** 186 * This is true if the caret is enabled, visible, and currently blinking. 187 * This is still true when the caret is enabled, visible, but in its "off" 188 * blink cycle. 189 */ 190 readonly attribute boolean caretVisible; 191 192 /** 193 * Show the caret even in selections. By default the caret is hidden unless the 194 * selection is collapsed. Use this function to show the caret even in selections. 195 * @param aVisibility true to show the caret in selections. false to hide. 196 * @return always NS_OK 197 */ 198 void setCaretVisibilityDuringSelection(in boolean visibility); 199 200 /** CharacterMove will move the selection one character forward/backward in the document. 201 * this will also have the effect of collapsing the selection if the aExtend = false 202 * the "point" of selection that is extended is considered the "focus" point. 203 * or the last point adjusted by the selection. 204 * @param aForward forward or backward if false 205 * @param aExtend should it collapse the selection of extend it? 206 */ 207 [can_run_script] 208 void characterMove(in boolean forward, in boolean extend); 209 210 /** PhysicalMove will move the selection one "unit" in a given direction 211 * within the document. 212 * this will also have the effect of collapsing the selection if the aExtend = false 213 * the "point" of selection that is extended is considered the "focus" point. 214 * or the last point adjusted by the selection. 215 * @param aDirection 216 * @param aAmount character/line; word/lineBoundary 217 * @param aExtend should it collapse the selection of extend it? 218 */ 219 [can_run_script] 220 void physicalMove(in short direction, in short amount, in boolean extend); 221 222 /** 223 * nsFrameSelection::PhysicalMove depends on the ordering of these values; 224 * do not change without checking there! 225 */ 226 const short MOVE_LEFT = 0; 227 const short MOVE_RIGHT = 1; 228 const short MOVE_UP = 2; 229 const short MOVE_DOWN = 3; 230 231 /** WordMove will move the selection one word forward/backward in the document. 232 * this will also have the effect of collapsing the selection if the aExtend = false 233 * the "point" of selection that is extended is considered the "focus" point. 234 * or the last point adjusted by the selection. 235 * @param aForward forward or backward if false 236 * @param aExtend should it collapse the selection of extend it? 237 */ 238 [can_run_script] 239 void wordMove(in boolean forward, in boolean extend); 240 241 /** LineMove will move the selection one line forward/backward in the document. 242 * this will also have the effect of collapsing the selection if the aExtend = false 243 * the "point" of selection that is extended is considered the "focus" point. 244 * or the last point adjusted by the selection. 245 * @param aForward forward or backward if false 246 * @param aExtend should it collapse the selection of extend it? 247 */ 248 [can_run_script] 249 void lineMove(in boolean forward, in boolean extend); 250 251 /** IntraLineMove will move the selection to the front of the line or end of the line 252 * in the document. 253 * this will also have the effect of collapsing the selection if the aExtend = false 254 * the "point" of selection that is extended is considered the "focus" point. 255 * or the last point adjusted by the selection. 256 * @param aForward forward or backward if false 257 * @param aExtend should it collapse the selection of extend it? 258 */ 259 [can_run_script] 260 void intraLineMove(in boolean forward, in boolean extend); 261 262 /** PageMove will move the selection one page forward/backward in the document. 263 * this will also have the effect of collapsing the selection if the aExtend = false 264 * the "point" of selection that is extended is considered the "focus" point. 265 * or the last point adjusted by the selection. 266 * @param aForward forward or backward if false 267 * @param aExtend should it collapse the selection of extend it? 268 */ 269 [can_run_script] 270 void pageMove(in boolean forward, in boolean extend); 271 272 /** CompleteScroll will move page view to the top or bottom of the document 273 * @param aForward forward or backward if false 274 */ 275 void completeScroll(in boolean forward); 276 277 /** CompleteMove will move page view to the top or bottom of the document 278 * this will also have the effect of collapsing the selection if the aExtend = false 279 * the "point" of selection that is extended is considered the "focus" point. 280 * or the last point adjusted by the selection. 281 * @param aForward forward or backward if false 282 * @param aExtend should it collapse the selection of extend it? 283 */ 284 [can_run_script] 285 void completeMove(in boolean forward, in boolean extend); 286 287 288 /** ScrollPage will scroll the page without affecting the selection. 289 * @param aForward scroll forward or backwards in selection 290 */ 291 void scrollPage(in boolean forward); 292 293 /** ScrollLine will scroll line up or down dependent on the boolean 294 * @param aForward scroll forward or backwards in selection 295 */ 296 void scrollLine(in boolean forward); 297 298 /** ScrollCharacter will scroll right or left dependent on the boolean 299 * @param aRight if true will scroll right. if not will scroll left. 300 */ 301 void scrollCharacter(in boolean right); 302 303 %{C++ 304 // Like the XPCOM method, but more convenient and flexible for C++ callers. Implemented in Selection.h 305 // TODO: Use `MOZ_CAN_RUN_SCRIPT`, but it's a bit tricky because whether it 306 // can run script depends on the SelectionScrollMode. 307 MOZ_CAN_RUN_SCRIPT_BOUNDARY inline nsresult ScrollSelectionIntoView( 308 mozilla::SelectionType, SelectionRegion, 309 const mozilla::ScrollAxis& aVertical, const mozilla::ScrollAxis& aHorizontal, 310 mozilla::ScrollFlags, mozilla::SelectionScrollMode); 311 MOZ_CAN_RUN_SCRIPT_BOUNDARY inline nsresult ScrollSelectionIntoView( 312 mozilla::SelectionType, SelectionRegion, 313 mozilla::SelectionScrollMode); 314 %} 315 }; 316 %{C++ 317 318 namespace mozilla { 319 320 // SelectionType should be used in internal handling code as it is type safe. 321 enum class SelectionType : RawSelectionType { 322 eInvalid = -1, 323 eNone = nsISelectionController::SELECTION_NONE, 324 eNormal = nsISelectionController::SELECTION_NORMAL, 325 eSpellCheck = nsISelectionController::SELECTION_SPELLCHECK, 326 eIMERawClause = nsISelectionController::SELECTION_IME_RAWINPUT, 327 eIMESelectedRawClause = nsISelectionController::SELECTION_IME_SELECTEDRAWTEXT, 328 eIMEConvertedClause = nsISelectionController::SELECTION_IME_CONVERTEDTEXT, 329 eIMESelectedClause = 330 nsISelectionController::SELECTION_IME_SELECTEDCONVERTEDTEXT, 331 eAccessibility = nsISelectionController::SELECTION_ACCESSIBILITY, 332 eFind = nsISelectionController::SELECTION_FIND, 333 eURLSecondary = nsISelectionController::SELECTION_URLSECONDARY, 334 eURLStrikeout = nsISelectionController::SELECTION_URLSTRIKEOUT, 335 eTargetText = nsISelectionController::SELECTION_TARGET_TEXT, 336 eHighlight = nsISelectionController::SELECTION_HIGHLIGHT, 337 }; 338 339 // kPresentSelectionTypes is selection types which may be displayed. 340 // I.e., selection types except eNone. 341 static const SelectionType kPresentSelectionTypes[] = { 342 SelectionType::eNormal, 343 SelectionType::eSpellCheck, 344 SelectionType::eIMERawClause, 345 SelectionType::eIMESelectedRawClause, 346 SelectionType::eIMEConvertedClause, 347 SelectionType::eIMESelectedClause, 348 SelectionType::eAccessibility, 349 SelectionType::eFind, 350 SelectionType::eURLSecondary, 351 SelectionType::eURLStrikeout, 352 SelectionType::eTargetText, 353 SelectionType::eHighlight, 354 }; 355 356 // Please include mozilla/dom/Selection.h for the following APIs. 357 constexpr bool IsValidRawSelectionType(RawSelectionType aRawSelectionType); 358 constexpr SelectionType ToSelectionType(RawSelectionType aRawSelectionType); 359 constexpr RawSelectionType ToRawSelectionType(SelectionType aSelectionType); 360 constexpr SelectionTypeMask ToSelectionTypeMask(SelectionType aSelectionType); 361 362 } // namespace mozilla 363 %}