1//////////////////////////////////////////////////////////////////////////////// 2// 3// ADOBE SYSTEMS INCORPORATED 4// Copyright 2007-2010 Adobe Systems Incorporated 5// All Rights Reserved. 6// 7// NOTICE: Adobe permits you to use, modify, and distribute this file 8// in accordance with the terms of the license agreement accompanying it. 9// 10//////////////////////////////////////////////////////////////////////////////// 11package flashx.textLayout.compose 12{ 13 import flashx.textLayout.container.ContainerController; 14 import flashx.textLayout.edit.ISelectionManager; 15 import flashx.textLayout.elements.ContainerFormattedElement; 16 import flashx.textLayout.elements.TextFlow; 17 18 /** 19 * IFlowComposer defines the interface for managing the layout and display of a text flow. 20 * 21 * <p>Text flows displayed with a flow composer implementation can be dynamic and interactive. 22 * A flow composer manages one or more display controller. Each controller is associated with 23 * a display object container (such as a Sprite) through which the lines created for the text 24 * flow are ultimately displayed. The following diagram illustrates the relationship between TextFlow, 25 * IFlowComposer, ContainerController, and DisplayObjectContainer objects:</p> 26 * 27 * <p><img src="../../../images/textLayout_singleController.gif" alt="IFlowComposer"></img></p> 28 * 29 * <p>A flow composer calculates which portion of a text flow fits in each container and 30 * adds the appropriate text lines to the container's display object. The IFlowComposer interface 31 * defines separate methods for layout calculations and for updating the display. IFlowComposer also 32 * defines methods for incrementally composing and updating a text flow. These methods can be used 33 * to avoid blocking the user interface when updating long text flows.</p> 34 * 35 * <p>In addition to managing text composition and display, a flow composer controls which container has focus, 36 * manages the display of the selection highlight (which can cross container boundaries), and provides 37 * direct access to all the TextLine objects in the flow.</p> 38 * 39 * <p>To use an IFlowComposer implementation, assign an instance of that implementation to the 40 * <code>flowComposer</code> property of a TextFlow object. Call the <code>updateAllControllers()</code> 41 * method to lay out and display the text in the containers attached to the flow composer.</p> 42 * 43 * <p><b>Note:</b> For simple, static text flows, you can also use the one of the text line factory classes. 44 * These factory classes will typically create lines with less overhead than a flow composer, but do not 45 * support editing, dynamic changes, or user interaction.</p> 46 * 47 * @see flashx.textLayout.container.ContainerController ContainerController 48 * @see FlowComposerBase 49 * @see StandardFlowComposer 50 * @see flashx.textLayout.elements.TextFlow TextFlow 51 * @see flashx.textLayout.factory.StringTextLineFactory StringTextLineFactory 52 * @see flashx.textLayout.factory.TextFlowTextLineFactory TextFlowTextLineFactory 53 * @playerversion Flash 10 54 * @playerversion AIR 1.5 55 * @langversion 3.0 56 */ 57 public interface IFlowComposer 58 { 59 /** 60 * The root element associated with this IFlowComposer instance. 61 * 62 * <p>Only a TextFlow object can be a root element.</p> 63 * 64 * @see flashx.textLayout.elements.ContainerFormattedElement ContainerFormattedElement 65 * 66 * @playerversion Flash 10 67 * @playerversion AIR 1.5 68 * @langversion 3.0 69 */ 70 function get rootElement():ContainerFormattedElement; 71 function setRootElement(newRootElement:ContainerFormattedElement):void; 72 73 /** 74 * The first invalid position in the root element, as an absolute position from the start of the flow. 75 * 76 * @playerversion Flash 10 77 * @playerversion AIR 1.5 78 * @langversion 3.0 79 */ 80 81 function get damageAbsoluteStart():int; 82 83 /** 84 * Composes the content of the root element and updates the display. 85 * 86 * <p>Text layout is typically conducted in two phases: composition and display. In the composition phase, 87 * the flow composer calculates how many lines are necesary to display the content as well as the position of these 88 * lines in the flow's display containers. In the display phase, 89 * the flow composer updates the display object children of its containers. The <code>updateAllControllers()</code> 90 * method is expected to carry out both phases. An efficient implementation will keep track of changes to content 91 * so that a full cycle of composition and display is only performed when necessary.</p> 92 * 93 * <p>This method updates all the text lines and the display list immediately and synchronously.</p> 94 * 95 * <p>If the contents of any container is changed, the method must return <code>true</code>.</p> 96 * 97 * @return true if anything changed. 98 * 99 * @playerversion Flash 10 100 * @playerversion AIR 1.5 101 * @langversion 3.0 102 * 103 */ 104 function updateAllControllers():Boolean; 105 106 /** 107 * Composes and updates the display up to and including the container at the specified index. 108 * 109 * <p>The <code>updateToController()</code> method is expected to both compose the content and 110 * update the display so that all containers up to and including the container at the specified index are current. 111 * For example, if you have a chain of twenty containers and specify an index of 10, 112 * <code>updateToController()</code> must ensures that the first through the tenth (indexes 0-9) containers 113 * are composed and displayed. Composition can stop at that point. If <code>controllerIndex</code> 114 * is -1 (or not specified), then all containers should be updated.</p> 115 * 116 * <p>This method updates all the text lines and the display list immediately and synchronously.</p> 117 * 118 * <p>If the contents of any container is changed, the method must return <code>true</code>.</p> 119 * 120 * @param controllerIndex index of the last container to update, by default will update all containers 121 * @return true if anything changed. 122 * 123 * @playerversion Flash 10 124 * @playerversion AIR 1.5 125 * @langversion 3.0 126 * 127 */ 128 129 function updateToController(index:int = int.MAX_VALUE):Boolean; 130 131 /** 132 * Sets the focus to the container that contains the location specified by the <code>absolutePosition</code> 133 * parameter. 134 * 135 * <p>It is the responsibility of the implementation to define what setting the focus means. For example, an 136 * implementation could use the built-in <code>focus</code> property of the Stage object (as long as the 137 * containers were InteractiveObjects) or the implementation could manage the focus some other way.</p> 138 * 139 * @param absolutePosition Specifies the position in the text flow of the container to receive focus. 140 * @param preferPrevious If true and the position is the before the first character in a container, sets focus to the end of 141 * the previous container. 142 * 143 * @see flash.display.Stage#focus 144 * 145 * @playerversion Flash 10 146 * @playerversion AIR 1.5 147 * @langversion 3.0 148 */ 149 150 function setFocus(absolutePosition:int,preferPrevious:Boolean=false):void 151 152 /** 153 * Calculates how many lines are necessary to display the content in the root element of the flow and the positions of these 154 * lines in the flow's display containers. 155 * 156 * <p>Implementations of this method should not update the display, but should save the results so that subsequent 157 * calls to <code>compose()</code> or <code>updateAllControllers()</code> do not perform an additional recomposition 158 * if the flow content has not changed.</p> 159 * 160 * <p>If the contents of any container have changed, the method must return <code>true</code>.</p> 161 * 162 * @return true if anything changed. 163 * 164 * @playerversion Flash 10 165 * @playerversion AIR 1.5 166 * @langversion 3.0 167 * 168 * @see #updateAllControllers() 169 * @see #updateToController() 170 */ 171 172 function compose():Boolean; 173 174 /** 175 * Composes the content of the root element up to the specified position. 176 * 177 * <p>If the contents of any container up to and including the container holding the content at the specified 178 * position has changed, the method returns <code>true</code>. If <code>absolutePosition</code> is greater than the length of the TextFlow 179 * (or not specified), then the entire flow is composed.</p> 180 * 181 * @param absolutePosition compose at least up to this position in the TextFlow. By default or if absolutePosition is past the end of the flow compose to the end of the flow. 182 * @return true if anything changed. 183 * 184 * @playerversion Flash 10 185 * @playerversion AIR 1.5 186 * @langversion 3.0 187 * 188 * @see #updateAllControllers() 189 * @see #updateToController() 190 */ 191 192 function composeToPosition(absolutePosition:int = int.MAX_VALUE):Boolean; 193 194 /** 195 * Composes the content of the root element up to and including the container at the specified index. 196 * 197 * <p>If the contents of any container up to and including the container at the specified 198 * index has changed, the method returns <code>true</code>. If <code>index</code> is greater than the number of controllers 199 * (or not specified), then all containers are composed.</p> 200 * 201 * @param controllerIndex compose at least up to this container in the TextFlow. If controllerIndex is greater than the number of controllers, compose to the end of the last container. 202 * @return true if anything changed. 203 * 204 * @playerversion Flash 10 205 * @playerversion AIR 1.5 206 * @langversion 3.0 207 * 208 * @see #updateAllControllers() 209 * @see #updateToController() 210 */ 211 212 function composeToController(index:int = int.MAX_VALUE):Boolean; 213 214 /** 215 * The number of containers assigned to this IFlowComposer instance. 216 * 217 * @playerversion Flash 10 218 * @playerversion AIR 1.5 219 * @langversion 3.0 220 */ 221 222 function get numControllers():int; 223 224 /** 225 * Adds a controller to this IFlowComposer instance. 226 * 227 * <p>The container is added to the end of the container list.</p> 228 * 229 * @param controller The ContainerController object to add. 230 * 231 * @playerversion Flash 10 232 * @playerversion AIR 1.5 233 * @langversion 3.0 234 */ 235 236 function addController(controller:ContainerController):void; 237 238 /** 239 * Adds a controller to this IFlowComposer instance at the specified index. 240 * 241 * <p>The list of controllers is 0-based (the first controller has an index of 0).</p> 242 * 243 * @param controller The ContainerController object to add. 244 * @param index A numeric index that specifies the position in the controller list at which to insert the ContainerController object. 245 * 246 * @playerversion Flash 10 247 * @playerversion AIR 1.5 248 * @langversion 3.0 249 */ 250 251 function addControllerAt(controller:ContainerController, index:int):void; 252 253 /** 254 * Removes a controller from this IFlowComposer instance. 255 * 256 * @param controller The ContainerController instance to remove. 257 * 258 * @playerversion Flash 10 259 * @playerversion AIR 1.5 260 * @langversion 3.0 261 */ 262 263 function removeController(controller:ContainerController):void; 264 265 /** 266 * Removes the controller at the specified index from this IFlowComposer instance. 267 * 268 * @param index The index of the ContainerController object to remove. 269 * 270 * @playerversion Flash 10 271 * @playerversion AIR 1.5 272 * @langversion 3.0 273 */ 274 275 function removeControllerAt(index:int):void 276 277 /** 278 * Removes all controllers from this IFlowComposer instance. 279 * 280 * @playerversion Flash 10 281 * @playerversion AIR 1.5 282 * @langversion 3.0 283 */ 284 function removeAllControllers():void; 285 286 /** 287 * Returns the ContainerController object at the specified index. 288 * 289 * @param index The index of the ContainerController object to return. 290 * @return the ContainerController object at the specified position. 291 * 292 * @playerversion Flash 10 293 * @playerversion AIR 1.5 294 * @langversion 3.0 295 */ 296 297 function getControllerAt(index:int):ContainerController; 298 299 /** 300 * Returns the index of the specified ContainerController object. 301 * 302 * @param controller A reference to the ContainerController object to find. 303 * @return the index of the specified ContainerController object or -1 if the controller is not attached to this flow composer. 304 * 305 * @playerversion Flash 10 306 * @playerversion AIR 1.5 307 * @langversion 3.0 308 */ 309 310 function getControllerIndex(controller:ContainerController):int; 311 312 /** 313 * Returns the index of the controller containing the content at the specified position. 314 * 315 * <p>A position can be considered to be the division between two characters or other elements of a text flow. If 316 * the value in <code>absolutePosition</code> is a position between the last character of one 317 * container and the first character of the next, then the preceding container is returned if 318 * the <code>preferPrevious</code> parameter is set to <code>true</code> and the later container is returned if 319 * the <code>preferPrevious</code> parameter is set to <code>false</code>.</p> 320 * 321 * <p>The method must return -1 if the content at the specified position is not in any container or is outside 322 * the range of positions in the text flow.</p> 323 * 324 * @param absolutePosition The position of the content for which the container index is sought. 325 * @param preferPrevious Specifies which container index to return when the position is between the last element in 326 * one container and the first element in the next. 327 * 328 * @return the index of the container controller or -1 if not found. 329 * 330 * @playerversion Flash 10 331 * @playerversion AIR 1.5 332 * @langversion 3.0 333 */ 334 335 function findControllerIndexAtPosition(absolutePosition:int,preferPrevious:Boolean=false):int; 336 337 /** 338 * Returns the sequential line number of the TextFlowLine object that contains the content at the specified position. 339 * 340 * <p>The number of the first line is 0 and the number of the last line is equal to the number of lines minus one. 341 * If the position specified in <code>absolutePosition</code> is past the end of the text flow, this method must return 342 * the number that will be assigned to the next new line added to the text flow (which is equal to the number of current lines).</p> 343 * 344 * <p>A position can be considered to be the division between two characters or other elements of a text flow. If 345 * the value in <code>absolutePosition</code> is a position between the last line of one 346 * container and the first line of the next, then the preceding container is returned if 347 * the <code>preferPrevious</code> parameter is set to <code>true</code> and the later container is returned if 348 * the <code>preferPrevious</code> parameter is set to <code>false</code>.</p> 349 * 350 * @param absolutePosition The position of the content for which you want the text line. 351 * @param preferPrevious Specifies which container index to return when the position is between the last line in 352 * one container and the first line in the next. 353 * 354 * @return the index of the text line at the specified position. If not found, treats as past the end and returns the 355 * number of lines. 356 * 357 * @playerversion Flash 10 358 * @playerversion AIR 1.5 359 * @langversion 3.0 360 */ 361 362 function findLineIndexAtPosition(absolutePosition:int,preferPrevious:Boolean = false):int; 363 364 /** 365 * Returns the TextFlowLine object containing the content at the specified position. 366 * 367 * <p>A position can be considered to be the division between two characters or other elements of a text flow. If 368 * the value in <code>absolutePosition</code> is a position between the last element of one 369 * line and the first element of the next, then the preceding line is returned if 370 * the <code>preferPrevious</code> parameter is set to <code>true</code> and the later line is returned if 371 * the <code>preferPrevious</code> parameter is set to <code>false</code>.</p> 372 * 373 * @param absolutePosition The position of the content for which you want the TextFlowLine object. 374 * @param preferPrevious Specifies which line to return when the position is between the last element of 375 * one line and the first element of the next. 376 * 377 * @return the TextFlowLine containing the content at the specified position, or null if not found. 378 * 379 * @playerversion Flash 10 380 * @playerversion AIR 1.5 381 * @langversion 3.0 382 */ 383 384 function findLineAtPosition(absolutePosition:int,preferPrevious:Boolean = false):TextFlowLine; 385 386 /** 387 * Returns the line with the specified line number. 388 * 389 * <p>The list of lines is numbered from zero to the number of lines minus one. If the value in <code>index</code> 390 * is outside the bounds of the list of lines, then this function returns <code>null</code>.</p> 391 * 392 * @param index The line number of the TextFlowLine object to return. 393 * @return the TextFlowLine with the specified line number, or <code>null</code>, if not found. 394 * 395 * @playerversion Flash 10 396 * @playerversion AIR 1.5 397 * @langversion 3.0 398 */ 399 function getLineAt(index:int):TextFlowLine; 400 401 /** 402 * The total number of lines composed in the flow. By default TLF does not compose the entire flow and this value may be innacruate. 403 * Use composeToPosition to get all lines composed. 404 * 405 * @playerversion Flash 10 406 * @playerversion AIR 1.5 407 * @langversion 3.0 408 */ 409 410 function get numLines():int; 411 412 /** 413 * Indicates whether any TextFlowLine objects between the beginning of the flow and the line containing the content at 414 * the specified position are marked as damaged. 415 * 416 * @param absolutePosition the last position in the area of interest 417 * @return true if any of the TextFlowLine objects from the start of the flow up to the line containing the content at 418 * <code>absolutePosition</code> are marked as damaged. 419 * 420 * @playerversion Flash 10 421 * @playerversion AIR 1.5 422 * @langversion 3.0 423 */ 424 425 function isDamaged(absolutePosition:int):Boolean; 426 427 428 /** 429 * True, if the flow composer is currently performing a composition operation. 430 * 431 * @playerversion Flash 10 432 * @playerversion AIR 1.5 433 * @langversion 3.0 434 */ 435 function get composing():Boolean; 436 437 /** 438 * The ISWFContext instance to be used for calls that must be made in a specific SWF context 439 * 440 * <p>Implementations of IFlowComposer should allow this property to be set so that users 441 * of the interface can create lines in a different SWF context than the one containing the 442 * implementation. A default implementation of ISWFContext should also be supplied.</p> 443 * 444 * @see flashx.elements.ISWFContext ISWFContext 445 * @playerversion Flash 10 446 * @playerversion AIR 1.5 447 * @langversion 3.0 448 */ 449 function get swfContext():ISWFContext; 450 function set swfContext(creator:ISWFContext):void; 451 452 /** 453 * Called by the TextFlow when the interaction manager changes. 454 * 455 * <p>Implementations of IFlowComposer should update event listeners and properties 456 * that reference the interaction manager.</p> 457 * 458 * @param newInteractionManager The new ISelectionManager instance. 459 * 460 * @playerversion Flash 10 461 * @playerversion AIR 1.5 462 * @langversion 3.0 463 */ 464 465 function interactionManagerChanged(newInteractionManager:ISelectionManager):void 466 467 /** Update the lengths in the lines to maintain mapping to the TextFlow. 468 * 469 * @param startPosition beginning of change in length 470 * @param deltaLength change in number of characters. 471 * @playerversion Flash 10 472 * @playerversion AIR 1.5 473 * @langversion 3.0 474 */ 475 function updateLengths(startPosition:int,deltaLength:int):void; 476 477 /** Mark lines as damaged and needing a recompose. 478 * @param damageStart beginning of range to damage 479 * @param damageLength number of characters to damage 480 * @param damageType type of damage. One of flashx.textLayout.compose.FlowDamageType 481 * @see flashx.textLayout.compose.FlowDamageType 482 * @playerversion Flash 10 483 * @playerversion AIR 1.5 484 * @langversion 3.0 485 */ 486 function damage(startPosition:int, damageLength:int, damageType:String):void; 487 } 488 489} 490
