[Gzz] PEG textnodeview_locate_cursor--humppake

[Asko Soukka]

===========================================================================================
PEG textnodeview_locate_cursor--humppake: Locating cursor in textnodeview 
with broken lines
===========================================================================================

:Authors:  Asko Soukka
:Date-Created: 2003-08-14
:Last-Modified: $Date: 2003/08/14 07:36:37 $
:Revision: $Revision: 1.1 $
:Status:   Current
:Scope:    Trivial
:Type:     Interface, Feature

Mudyc asked me to think how text cursor could be located within
TextNodeView (currently ``org.fenfire.view.TextNodeView``). This PEG
describes my solution proposal: two new methods for TextNodeView. One
returning the cursor position according to coordinates within
TextNodeView and another returning the coordinates of the cursor
according to it's position (often referred as offset) within the text.

Issues
======

Who knows position of cursors?

        RESOLVED: The position is usually stored within demo
        application. A spesific Cursor class may be used
        (``org.fengire.view.lava.Cursor``).
        
        NOTE: The term `position` means here only cursor's offset
        within the text string.

But there is also a method ``getCursorOffset`` in
``org.fenfire.view.lava.TextHandler`` (`the `TextNodeView``
inherits). Does it have any role?

        RESOLVED: AFAIK, currently it's not used anywhere. ``Cursor``
        is used instead of it.

Who knows how text's lines are broken?

        RESOLVED: Only the used ``TextNodeView`` knows. It uses
        LibVob's linebreaking code (``org.nongnu.libvob.linebreaking``).
        The linebreaking information is formed only when needed (when
        creating a placeable object) and is not stored.

How the information of linebreaking can be reached?

        RESOLVED: The information is not stored within
        ``TextNodeView``, but it could be reconstructed. 

Where the information of linebreaking could be reconstructed?

        RESOLVED: The reconstruction is complex and is most practical
        to do also within ``TextNodeView``, since it has already the
        supportive  methods needed for easy use of linebreaking lib.

        In ``TextNodeView`` only the text content is needed for
        linebreaking. When creating a placeable TextNodeView object,
        the text is fetched from the current node (needed parameters
        are current ``ConstGraph`` and current node)

When the linebreaking information is needed?

        RESOLVED: With mudyc we ended up to two main use cases.

        1) I know the cursor offset, but in which coordinates I should
           draw the cursor into?

        2) I click the text with mouse and know the coordinates I
           clicked, but how I set the cursor offset according to those
           coordinates? (this should cover also the selection of text
           using mouse)
           
How the needs could be filled?

        RESOLVED: According to the previous use cases, I suggest two
        new methods into ``TextNodeView``. They will reconstruct the
        linebreaking information using supportive methods already in
        ``TextNodeView`` and use available public methods of
        ``linebreaking.HBroken`` and ``linebreaking.HChain`` to
        collect the information needed.
           
        The first method returns the cursor position according to
        given coordinates within TextNodeView and another returns the
        coordinates of the cursor according to it's given position
        (often referred as offset) within the text.

        The following should be always true, when a has a proper
        (existing) text cursor offset value::

                a == TextNodeView.getPos(TextNodeView.getXY(a))

Changes
=======

Into ``org.fenfire.view.TextNodeView``::

    /** Get position of the first character placed
     * after given coordinates.
     */
    public int getPos(ConstGraph g, Object node, float x, float y);

    /** Get coordinates before the given character position.
     * The Y coordinate is located below the line.
     */
    public void getXY(ConstGraph g, Object node, int pos, float[] xy);


Implementation notes
====================

``TextNodeView.getXY()`` returns y coordinate located below the line,
because the ``linebreaking.Hbroken.getLineOffset()`` also does that.


-- 
Asko Soukka <address@hidden>
<http://www.iki.fi/asko.soukka/>