[[BackLinksMenu]]

[[TicketQuery(summary=WRAPPING_TEXT_RENDERING_R0, format=table, col=summary|owner|status|type|component|priority|effort|importance, rows=description|analysis_owners|analysis_reviewers|analysis_score|design_owners|design_reviewers|design_score|implementation_owners|implementation_reviewers|implementation_score|test_owners|test_reviewers|test_score|)]]



= Analysis =

== Overview ==
 * The ability of text to wrap around objects.
  * The objects could wrap the text as follows:
   * none - text is not wrapped
   * before - text wraps only on the left side
   * after - text wraps only on the right side
   * parallel - text wraps from both sides
  * Default value should be parallel.
  * Modification of wrapping options will be available from a separate hud added to the HotText halo menu. It will contain a group of radio buttons to switch between No Wrapping, Before, After and Parallel.
  * Text can be flowed/wrapped only around overlapping objects (frames, etc.), that is - objects that have a higher z-order than the current Frame.
  * The way of wrapping will depend on the available space for flowing of the text around the overlapping objects.
   * The following strategy will be considered
    * Flowing text line by line (text alignment should not be taken into account on the text sides displayed around the overlapping object).
     [[Image(source:branches/private/vlado/sophie2-platform/doc/spec-diagrams/LineByLineTextFlowing.png)]]
    * Flowing text on intersection blocks will not be used in Sophie 2.0. If such functionality is desired it can be mimicked by creation of separate Frames.
     [[Image(source:branches/private/vlado/sophie2-platform/doc/spec-diagrams/IntersectionBlockTextFlowing.png)]]
   * A kind of priority (weight) will be present to estimate the different options for text layout in various cases of overlapping.
 * Text layout inside a Frame.
  * Text is divided into the following parts which define scopes for the text elements:
   * Text - the whole flowing text.
   * Text Part - part of the whole text, that is displayed as content of a Frame.
   * Line - one line of visible text inside a Frame. It is composed of one or more line segments, depending on overlapping with other objects (frames, etc.)
   * Segment (Line Part) - part of a line wrapped around two objects, object and border or two borders of the container Frame.

== Task requirements ==
 * Refine the existing text layout algorithm.
 * Provide layout functionality for accurate calculation of Text Parts depending on the present Frames (needed for [wiki:TEXT_CHAINING_BEHAVIOUR_R0] and [wiki:TEXT_AUTO_CHAIN_BEHAVIOUR_R0]).
 * Fixing a known bug with layout algorithm specified at [http://www.sophie2.org/trac/wiki/TEXT_INPLACE_EDITOR_R0#Implementation].
 * If there is time a simple line by line text flowing will be added.

== Task result ==
The result should be source code.

== Implementation idea ==
 * Hill climbing algorithm is used for laying out text (a general implementation is already present).
  * Check [http://en.wikipedia.org/wiki/Hill_climbing Hill Climbing Algorithm at Wikipedia] for more information.
  * The roles in the algorithm for the purpose of HotTextLayout:
   * Vertex - a collection of vertex fields, such as text range (a specific Segment) and its supported properties (scope, area, position properties, etc.) 
   * Edge - represents a placement (positioning) operation for the next Segment depending on the previous Segment (it is the concrete kind of transition from a Vertex to one of its neighboring Vertex-s)
   * Path - represents a layout of some text (group of Segments, Line or Text Part) with a calculated weight, or "badness" (it is a collection of edges defining the path from one Vertex to another).
  * The goal is to layout the text according to the Path with lowest weight ("badness").
 * The algorithm can be extended with:
  * a better separation of Segments in relation to the needs of wrapping functionality.
  * a better Segment handling and calculations.
  * a better estimation of the weight ("badness") in different use cases.

== Related ==

[wiki:TEXT_CHAINING_BEHAVIOUR_R0]

[wiki:TEXT_AUTO_CHAIN_BEHAVIOUR_R0]

[wiki:SCENE_COMMONS]

[wiki:SCENE_COMMONS_R0]

[wiki:SMOOTH_TEXT_RENDERING_R0]

== How to demo ==
 * A simple line by line text flowing demo (if implemented)
  * Start the application
  * Create new book
  * Inside the book create new text frame and type some text (you could use lorem ipsum generator for better result - http://www.lipsum.com/)
  * Place another frame on top of the text frame. The text should be flowed around the second frame.

= Design =
 * Improvements in the Hill climbing algorithm for finding the best path
  * Replace EdgeKind.OPEN_SEGMENT, EdgeKind.CLOSE_SEGMENT and EdgeKind.ATOM with a single EdgeKind.SEGMENT. The effects of this modification include:
   * EdgeKind.SEGMENT becomes the smallest unbreakable EdgeKind (atomic transition) in the algorithm.
   * (advantage) The number of transitions in the algorithm vastly decrease, generally resulting in a better layout performance. Here is an example for a one line text with 2 segments:
    * ''Old Solution'': OPEN_TEXT -> OPEN_PART -> OPEN_LINE -> OPEN_SEGMENT -> ATOM -> CLOSE_SEGMENT -> OPEN_SEGMENT -> ATOM -> CLOSE_SEGMENT -> CLOSE_LINE -> CLOSE_PART -> CLOSE_TEXT
    * ''New Solution'': OPEN_TEXT -> OPEN_PART -> OPEN_LINE -> SEGMENT -> SEGMENT -> CLOSE_LINE -> CLOSE_PART -> CLOSE_TEXT
   * (drawback) EdgeKind.SEGMENT has to be more complex to handle the following cases, some of which make more sense to a segment as a whole (in the old solution the responsibilities were spread between OPEN_SEGMENT, CLOSE_SEGMENT and ATOM EdgeKinds):
    * Badness calculation
    * Breaks - part, line and segment break
    * Ascent
    * Descent
    * Gap
    * White space
    * Tracking
    * Drawing
  * Estimation of badness by importance:
   * Characters left (not laid out in the area)
   * Space occupied by the text in the area. Concrete badness factors related to this are:
    * Spacing
    * White extra
    * Ascent
    * Descent
   * Broken word
   * Shrunk tracking
   * Shrunk spacing
 * Calculation of Text Parts for the text chaining
  * Add the following:
   * Method HotTextLayout.canFitInShape and (static method) LayoutBuilder.canFit to check if a text can be flowed into an area
   * Method HotTextLayout.getTextParts and (static method) LayoutBuilder.getTextParts to return the separation of a text into parts that can be flowed into a sequence of areas
  * Implementation should be straightforward using the layout algorithm
 * Fix of the bug specified at [http://www.sophie2.org/trac/wiki/TEXT_INPLACE_EDITOR_R0#Implementation]: correct Atom.canFit method to pass the atom's height as 4th argument, not the atom's y-position.
 * Eliminate part of the fake implementations in the layout functionality
 * Fix warnings, add Javadoc and comments to all classes in org.sophie2.base.model.text.layout
 * Unit Tests: [3022]

Design related code merged to the trunk at [3026];

= Implementation =
The following code is committed to the clean branch (updated from trunk) on vlado/trunk-changes
[3192]
[3194]
[3195]

= Testing =

= Comments =
 * The hud location of the wrapping options will be analised in a next revision following the concept of text halo menu. - vlado