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#include "domstubs.idl" 8 9interface nsIContent; 10 11webidl Document; 12webidl Element; 13webidl Node; 14webidl Selection; 15 16[scriptable, builtinclass, uuid(87ee993e-985f-4a43-a974-0d9512da2fb0)] 17interface nsIHTMLEditor : nsISupports 18{ 19%{C++ 20 typedef short EAlignment; 21%} 22 23 // used by GetAlignment() 24 const short eLeft = 0; 25 const short eCenter = 1; 26 const short eRight = 2; 27 const short eJustify = 3; 28 29 30 /* ------------ Inline property methods -------------- */ 31 32 /** 33 * SetInlineProperty() sets the aggregate properties on the current selection 34 * 35 * @param aProperty the property to set on the selection 36 * @param aAttribute the attribute of the property, if applicable. 37 * May be null. 38 * Example: aProperty="font", aAttribute="color" 39 * @param aValue if aAttribute is not null, the value of the attribute. 40 * May be null. 41 * Example: aProperty="font", aAttribute="color", 42 * aValue="0x00FFFF" 43 */ 44 [can_run_script] 45 void setInlineProperty(in AString aProperty, 46 in AString aAttribute, 47 in AString aValue); 48 49 /** 50 * getInlinePropertyWithAttrValue() gets aggregate properties of the current 51 * selection. All object in the current selection are scanned and their 52 * attributes are represented in a list of Property object. 53 * 54 * @param aProperty the property to get on the selection 55 * @param aAttribute the attribute of the property, if applicable. 56 * May be null. 57 * Example: aProperty="font", aAttribute="color" 58 * @param aValue if aAttribute is not null, the value of the attribute. 59 * May be null. 60 * Example: aProperty="font", aAttribute="color", 61 * aValue="0x00FFFF" 62 * @param aFirst [OUT] PR_TRUE if the first text node in the 63 * selection has the property 64 * @param aAny [OUT] PR_TRUE if any of the text nodes in the 65 * selection have the property 66 * @param aAll [OUT] PR_TRUE if all of the text nodes in the 67 * selection have the property 68 */ 69 [can_run_script] 70 AString getInlinePropertyWithAttrValue(in AString aProperty, 71 in AString aAttribute, 72 in AString aValue, 73 out boolean aFirst, 74 out boolean aAny, 75 out boolean aAll); 76 77 /** 78 * removeInlineProperty() removes a property which changes inline style of 79 * text. E.g., bold, italic, super and sub. 80 * 81 * @param aProperty Tag name whcih represents the inline style you want to 82 * remove. E.g., "strong", "b", etc. 83 * If "href", <a> element which has href attribute will be 84 * removed. 85 * If "name", <a> element which has non-empty name 86 * attribute will be removed. 87 * @param aAttribute If aProperty is "font", aAttribute should be "face", 88 * "size", "color" or "bgcolor". 89 */ 90 [can_run_script] 91 void removeInlineProperty(in AString aProperty, in AString aAttribute); 92 93 /* ------------ HTML content methods -------------- */ 94 95 /** 96 * Tests if a node is a BLOCK element according the the HTML 4.0 DTD. 97 * This does NOT consider CSS effect on display type 98 * 99 * @param aNode the node to test 100 */ 101 boolean nodeIsBlock(in Node node); 102 103 /** 104 * Insert some HTML source at the current location 105 * 106 * @param aInputString the string to be inserted 107 */ 108 [can_run_script] 109 void insertHTML(in AString aInputString); 110 111 /** 112 * Rebuild the entire document from source HTML 113 * Needed to be able to edit HEAD and other outside-of-BODY content 114 * 115 * @param aSourceString HTML source string of the entire new document 116 */ 117 [can_run_script] 118 void rebuildDocumentFromSource(in AString aSourceString); 119 120 /** 121 * Insert an element, which may have child nodes, at the selection 122 * Used primarily to insert a new element for various insert element dialogs, 123 * but it enforces the HTML 4.0 DTD "CanContain" rules, so it should 124 * be useful for other elements. 125 * 126 * @param aElement The element to insert 127 * @param aDeleteSelection Delete the selection before inserting 128 * If aDeleteSelection is PR_FALSE, then the element is inserted 129 * after the end of the selection for all element except 130 * Named Anchors, which insert before the selection 131 */ 132 [can_run_script] 133 void insertElementAtSelection(in Element aElement, 134 in boolean aDeleteSelection); 135 136 /** 137 * Set the BaseURL for the document to the current URL 138 * but only if the page doesn't have a <base> tag 139 * This should be done after the document URL has changed, 140 * such as after saving a file 141 * This is used as base for relativizing link and image urls 142 */ 143 void updateBaseURL(); 144 145 146 /* ------------ Selection manipulation -------------- */ 147 /* Should these be moved to Selection? */ 148 149 /** 150 * Set the selection at the suppled element 151 * 152 * @param aElement An element in the document 153 */ 154 [can_run_script] 155 void selectElement(in Element aElement); 156 157 /** 158 * getParagraphState returns what block tag paragraph format is in 159 * the selection. 160 * @param aMixed True if there is more than one format 161 * @return Name of block tag. "" is returned for none. 162 */ 163 AString getParagraphState(out boolean aMixed); 164 165 /** 166 * getFontFaceState returns what font face is in the selection. 167 * @param aMixed True if there is more than one font face 168 * @return Name of face. Note: "tt" is returned for 169 * tt tag. "" is returned for none. 170 */ 171 [can_run_script] 172 AString getFontFaceState(out boolean aMixed); 173 174 /** 175 * getHighlightColorState returns what the highlight color of the selection. 176 * @param aMixed True if there is more than one font color 177 * @return Color string. "" is returned for none. 178 */ 179 [can_run_script] 180 AString getHighlightColorState(out boolean aMixed); 181 182 /** 183 * getListState returns what list type is in the selection. 184 * @param aMixed True if there is more than one type of list, or 185 * if there is some list and non-list 186 * @param aOL The company that employs me. No, really, it's 187 * true if an "ol" list is selected. 188 * @param aUL true if an "ul" list is selected. 189 * @param aDL true if a "dl" list is selected. 190 */ 191 void getListState(out boolean aMixed, out boolean aOL, out boolean aUL, 192 out boolean aDL); 193 194 /** 195 * getListItemState returns what list item type is in the selection. 196 * @param aMixed True if there is more than one type of list item, or 197 * if there is some list and non-list 198 * XXX This ignores `<li>` element selected state. 199 * For example, even if `<li>` and `<dt>` are selected, 200 * this is set to false. 201 * @param aLI true if "li" list items are selected. 202 * @param aDT true if "dt" list items are selected. 203 * @param aDD true if "dd" list items are selected. 204 */ 205 void getListItemState(out boolean aMixed, out boolean aLI, 206 out boolean aDT, out boolean aDD); 207 208 /** 209 * getAlignment returns what alignment is in the selection. 210 * @param aMixed Always returns false. 211 * @param aAlign enum value for first encountered alignment 212 * (left/center/right) 213 */ 214 [can_run_script] 215 void getAlignment(out boolean aMixed, out short aAlign); 216 217 /** 218 * Document me! 219 * 220 */ 221 [can_run_script] 222 void makeOrChangeList(in AString aListType, in boolean entireList, 223 in AString aBulletType); 224 225 /** 226 * removeList removes list items (<li>, <dd>, and <dt>) and list structures 227 * (<ul>, <ol>, and <dl>). 228 * 229 * @param aListType Unused. 230 */ 231 [can_run_script] 232 void removeList(in AString aListType); 233 234 /** 235 * GetElementOrParentByTagName() returns an inclusive ancestor element whose 236 * name matches aTagName from aNode or anchor node of Selection to <body> 237 * element or null if there is no element matching with aTagName. 238 * 239 * @param aTagName The tag name which you want to look for. 240 * Must not be empty string. 241 * If "list", the result may be <ul>, <ol> or <dl> 242 * element. 243 * If "td", the result may be <td> or <th>. 244 * If "href", the result may be <a> element 245 * which has "href" attribute with non-empty value. 246 * If "anchor", the result may be <a> which has 247 * "name" attribute with non-empty value. 248 * @param aNode If non-null, this starts to look for the result 249 * from it. Otherwise, i.e., null, starts from 250 * anchor node of Selection. 251 * @return If an element which matches aTagName, returns 252 * an Element. Otherwise, nullptr. 253 */ 254 Element getElementOrParentByTagName(in AString aTagName, 255 in Node aNode); 256 257 /** 258 * getSelectedElement() returns a "selected" element node. "selected" means: 259 * - there is only one selection range 260 * - the range starts from an element node or in an element 261 * - the range ends at immediately after same element 262 * - and the range does not include any other element nodes. 263 * Additionally, only when aTagName is "href", this thinks that an <a> 264 * element which has non-empty "href" attribute includes the range, the 265 * <a> element is selected. 266 * 267 * @param aTagName Case-insensitive element name. 268 * If empty string, this returns any element node or null. 269 * If "href", this returns an <a> element which has 270 * non-empty "href" attribute or null. 271 * If "anchor", this returns an <a> element which has 272 * non-empty "name" attribute or null. 273 * Otherwise, returns an element node whose name is 274 * same as aTagName or null. 275 * @return A "selected" element. 276 */ 277 nsISupports getSelectedElement(in AString aTagName); 278 279 /** 280 * Return a new element with default attribute values 281 * 282 * This does not rely on the selection, and is not sensitive to context. 283 * 284 * Used primarily to supply new element for various insert element dialogs 285 * (Image, Link, NamedAnchor, Table, and HorizontalRule 286 * are the only returned elements as of 7/25/99) 287 * 288 * @param aTagName The HTML tagname 289 * Special input values for Links and Named anchors: 290 * Use "href" to get a link node 291 * (an "A" tag with the "href" attribute set) 292 * Use "anchor" or "namedanchor" to get a named anchor node 293 * (an "A" tag with the "name" attribute set) 294 * @return The new element created. 295 */ 296 [can_run_script] 297 Element createElementWithDefaults(in AString aTagName); 298 299 /** 300 * Insert an link element as the parent of the current selection 301 * 302 * @param aElement An "A" element with a non-empty "href" attribute 303 */ 304 [can_run_script] 305 void insertLinkAroundSelection(in Element aAnchorElement); 306 307 /** 308 * Set the value of the "bgcolor" attribute on the document's <body> element 309 * 310 * @param aColor The HTML color string, such as "#ffccff" or "yellow" 311 */ 312 [can_run_script] 313 void setBackgroundColor(in AString aColor); 314 315 /** 316 * A boolean which is true is the HTMLEditor has been instantiated 317 * with CSS knowledge and if the CSS pref is currently checked 318 * 319 * @return true if CSS handled and enabled 320 */ 321 [setter_can_run_script] attribute boolean isCSSEnabled; 322 323 /** 324 * checkSelectionStateForAnonymousButtons() may refresh editing UI such as 325 * resizers, inline-table-editing UI, absolute positioning UI for current 326 * Selection and focus state. When this method shows or hides UI, the 327 * editor (and/or its document/window) could be broken by mutation observers. 328 * FYI: Current user in script is only BlueGriffon. 329 */ 330 [can_run_script] 331 void checkSelectionStateForAnonymousButtons(); 332 333 boolean isAnonymousElement(in Element aElement); 334 335 /** 336 * A boolean indicating if a return key pressed in a paragraph creates 337 * another paragraph or just inserts a <br> at the caret 338 * 339 * @return true if CR in a paragraph creates a new paragraph 340 */ 341 attribute boolean returnInParagraphCreatesNewParagraph; 342}; 343 344