nsIHTMLEditor.idl (13082B)
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 9 interface nsIContent; 10 11 webidl Document; 12 webidl Element; 13 webidl Node; 14 webidl Selection; 15 16 [scriptable, builtinclass, uuid(87ee993e-985f-4a43-a974-0d9512da2fb0)] 17 interface 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. This checks whether the computed 97 * style of the element is block or not. 98 * 99 * @param aNode the node to test 100 */ 101 [can_run_script] 102 boolean nodeIsBlock(in Node aNode); 103 104 /** 105 * Insert some HTML source at the current location 106 * 107 * @param aInputString the string to be inserted 108 */ 109 [can_run_script] 110 void insertHTML(in AString aInputString); 111 112 /** 113 * Insert an element, which may have child nodes, at the selection 114 * Used primarily to insert a new element for various insert element dialogs, 115 * but it enforces the HTML 4.0 DTD "CanContain" rules, so it should 116 * be useful for other elements. 117 * 118 * @param aElement The element to insert 119 * @param aDeleteSelection Delete the selection before inserting 120 * If aDeleteSelection is PR_FALSE, then the element is inserted 121 * after the end of the selection for all element except 122 * Named Anchors, which insert before the selection 123 */ 124 [can_run_script] 125 void insertElementAtSelection(in Element aElement, 126 in boolean aDeleteSelection); 127 128 /** 129 * Set the BaseURL for the document to the current URL 130 * but only if the page doesn't have a <base> tag 131 * This should be done after the document URL has changed, 132 * such as after saving a file 133 * This is used as base for relativizing link and image urls 134 */ 135 void updateBaseURL(); 136 137 138 /* ------------ Selection manipulation -------------- */ 139 /* Should these be moved to Selection? */ 140 141 /** 142 * Set the selection at the suppled element 143 * 144 * @param aElement An element in the document 145 */ 146 [can_run_script] 147 void selectElement(in Element aElement); 148 149 /** 150 * getParagraphState returns what block tag paragraph format is in 151 * the selection. 152 * @param aMixed True if there is more than one format 153 * @return Name of block tag. "" is returned for none. 154 */ 155 AString getParagraphState(out boolean aMixed); 156 157 /** 158 * getFontFaceState returns what font face is in the selection. 159 * @param aMixed True if there is more than one font face 160 * @return Name of face. Note: "tt" is returned for 161 * tt tag. "" is returned for none. 162 */ 163 [can_run_script] 164 AString getFontFaceState(out boolean aMixed); 165 166 /** 167 * getHighlightColorState returns what the highlight color of the selection. 168 * @param aMixed True if there is more than one font color 169 * @return Color string. "" is returned for none. 170 */ 171 [can_run_script] 172 AString getHighlightColorState(out boolean aMixed); 173 174 /** 175 * getListState returns what list type is in the selection. 176 * @param aMixed True if there is more than one type of list, or 177 * if there is some list and non-list 178 * @param aOL The company that employs me. No, really, it's 179 * true if an "ol" list is selected. 180 * @param aUL true if an "ul" list is selected. 181 * @param aDL true if a "dl" list is selected. 182 */ 183 void getListState(out boolean aMixed, out boolean aOL, out boolean aUL, 184 out boolean aDL); 185 186 /** 187 * getListItemState returns what list item type is in the selection. 188 * @param aMixed True if there is more than one type of list item, or 189 * if there is some list and non-list 190 * XXX This ignores `<li>` element selected state. 191 * For example, even if `<li>` and `<dt>` are selected, 192 * this is set to false. 193 * @param aLI true if "li" list items are selected. 194 * @param aDT true if "dt" list items are selected. 195 * @param aDD true if "dd" list items are selected. 196 */ 197 void getListItemState(out boolean aMixed, out boolean aLI, 198 out boolean aDT, out boolean aDD); 199 200 /** 201 * getAlignment returns what alignment is in the selection. 202 * @param aMixed Always returns false. 203 * @param aAlign enum value for first encountered alignment 204 * (left/center/right) 205 */ 206 [can_run_script] 207 void getAlignment(out boolean aMixed, out short aAlign); 208 209 /** 210 * Document me! 211 * 212 */ 213 [can_run_script] 214 void makeOrChangeList(in AString aListType, in boolean entireList, 215 in AString aBulletType); 216 217 /** 218 * removeList removes list items (<li>, <dd>, and <dt>) and list structures 219 * (<ul>, <ol>, and <dl>). 220 * 221 * @param aListType Unused. 222 */ 223 [can_run_script] 224 void removeList(in AString aListType); 225 226 /** 227 * GetElementOrParentByTagName() returns an inclusive ancestor element whose 228 * name matches aTagName from aNode or anchor node of Selection to <body> 229 * element or null if there is no element matching with aTagName. 230 * 231 * @param aTagName The tag name which you want to look for. 232 * Must not be empty string. 233 * If "list", the result may be <ul>, <ol> or <dl> 234 * element. 235 * If "td", the result may be <td> or <th>. 236 * If "href", the result may be <a> element 237 * which has "href" attribute with non-empty value. 238 * If "anchor", the result may be <a> which has 239 * "name" attribute with non-empty value. 240 * @param aNode If non-null, this starts to look for the result 241 * from it. Otherwise, i.e., null, starts from 242 * anchor node of Selection. 243 * @return If an element which matches aTagName, returns 244 * an Element. Otherwise, nullptr. 245 */ 246 Element getElementOrParentByTagName(in AString aTagName, 247 in Node aNode); 248 249 /** 250 * getSelectedElement() returns a "selected" element node. "selected" means: 251 * - there is only one selection range 252 * - the range starts from an element node or in an element 253 * - the range ends at immediately after same element 254 * - and the range does not include any other element nodes. 255 * Additionally, only when aTagName is "href", this thinks that an <a> 256 * element which has non-empty "href" attribute includes the range, the 257 * <a> element is selected. 258 * 259 * @param aTagName Case-insensitive element name. 260 * If empty string, this returns any element node or null. 261 * If "href", this returns an <a> element which has 262 * non-empty "href" attribute or null. 263 * If "anchor", this returns an <a> element which has 264 * non-empty "name" attribute or null. 265 * Otherwise, returns an element node whose name is 266 * same as aTagName or null. 267 * @return A "selected" element. 268 */ 269 nsISupports getSelectedElement(in AString aTagName); 270 271 /** 272 * Return a new element with default attribute values 273 * 274 * This does not rely on the selection, and is not sensitive to context. 275 * 276 * Used primarily to supply new element for various insert element dialogs 277 * (Image, Link, NamedAnchor, Table, and HorizontalRule 278 * are the only returned elements as of 7/25/99) 279 * 280 * @param aTagName The HTML tagname 281 * Special input values for Links and Named anchors: 282 * Use "href" to get a link node 283 * (an "A" tag with the "href" attribute set) 284 * Use "anchor" or "namedanchor" to get a named anchor node 285 * (an "A" tag with the "name" attribute set) 286 * @return The new element created. 287 */ 288 [can_run_script] 289 Element createElementWithDefaults(in AString aTagName); 290 291 /** 292 * Insert an link element as the parent of the current selection 293 * 294 * @param aElement An "A" element with a non-empty "href" attribute 295 */ 296 [can_run_script] 297 void insertLinkAroundSelection(in Element aAnchorElement); 298 299 /** 300 * Set the value of the "bgcolor" attribute on the document's <body> element 301 * 302 * @param aColor The HTML color string, such as "#ffccff" or "yellow" 303 */ 304 [can_run_script] 305 void setBackgroundColor(in AString aColor); 306 307 /** 308 * A boolean which is true is the HTMLEditor has been instantiated 309 * with CSS knowledge and if the CSS pref is currently checked 310 * 311 * @return true if CSS handled and enabled 312 */ 313 [setter_can_run_script] attribute boolean isCSSEnabled; 314 315 /** 316 * checkSelectionStateForAnonymousButtons() may refresh editing UI such as 317 * resizers, inline-table-editing UI, absolute positioning UI for current 318 * Selection and focus state. When this method shows or hides UI, the 319 * editor (and/or its document/window) could be broken by mutation observers. 320 * FYI: Current user in script is only BlueGriffon. 321 */ 322 [can_run_script] 323 void checkSelectionStateForAnonymousButtons(); 324 325 boolean isAnonymousElement(in Element aElement); 326 327 /** 328 * A boolean indicating if a return key pressed in a paragraph creates 329 * another paragraph or just inserts a <br> at the caret 330 * 331 * @return true if CR in a paragraph creates a new paragraph 332 */ 333 attribute boolean returnInParagraphCreatesNewParagraph; 334 };