Someone please explain ‘MouseEvent.OfX/OfY’

[tig]

The api docs are not clear.

I've looked at the code that uses these members and just got more confused.

Now that View.OnMouseEvent provides 'MouseEvent.X/Y' as Bounds relative I can't even. 😉

[BDisp]

There are to provide the mouse position offset from the grabbed view. It's calculated and processed on the Application mouse event. If the current mouse position is on another view than the grabbed view, the grabbed view receive the mouse event with view relative coordinate and the OfX/OfY gives the offset relative on the real mouse position. Thus the grabbed view know how much X/Y location it need to scroll. This give to the grabbed view more control about how it need to handled with the new position, to check if it's valid or not and take the right actions.

[tig]

Here's my current draft of updated docs based on the above.

/// <summary>
/// Provides the X (column) mouse position offset from the grabbed view (see <see cref="Application.GrabMouse"/>.
/// </summary>
/// <remarks>
/// Calculated and processed in <see cref="Application.OnMouseEvent(MouseEventEventArgs)"/>.
/// Whichever view that has called <see cref="Application.GrabMouse"/>, will receive all the mouse event
/// with <see cref="View.Bounds"/> relative coordinates. The <see cref="OfX"/> and <see cref="OfY"/> provide
/// the screen-relative offset of these coordinates.
/// Using these properties, the view that has grabbed the mouse will know how much the mouse has moved.
/// </remarks>
public int OfX { get; set; }

/// <summary>
/// Provides the Y (row) mouse position offset from the grabbed view (see <see cref="Application.GrabMouse"/>.
/// </summary>
/// <remarks>
/// Calculated and processed in <see cref="Application.OnMouseEvent(MouseEventEventArgs)"/>.
/// Whichever view that has called <see cref="Application.GrabMouse"/>, will receive all the mouse event
/// with <see cref="View.Bounds"/> relative coordinates. The <see cref="OfX"/> and <see cref="OfY"/> provide
/// the screen-relative offset of these coordinates.
/// Using these properties, the view that has grabbed the mouse will know how much the mouse has moved.
/// </remarks>
public int OfY { get; set; }

Given the mouse coordinates passed to View.OnMouseEvent are now Bounds-relative, I'm wondering if views could use View.BoundsToScreen (new API in #2920) instead of using these properties?

I may still not be understanding this all.

[tig]

@BDisp, there are two Views (not including Toplevel) that reference either MouseEvent.OfX or MouseEvent.OfY (which I've renamed to make more clear):

In #3289, I'm asking why Menu does.

Can you help me understand what this code in TextView is attempting to do?

   private int PositionCursor (MouseEvent ev)
   {
       // We could also set the cursor position.
       int x;
       int pX = TextModel.GetColFromX (_text, ScrollOffset, ev.X);

       if (_text.Count == 0)
       {
           x = pX - ev.OfX;
       }
       else
       {
           x = pX;
       }

       return PositionCursor (x, false);
   }

[BDisp]

When the mouse isn't over the TextField while is selecting it can recognize on which direction the mouse is moving and increment/decrease the selected text because it grabbed the mouse.

[tig]

Makes sense if there's text.

But, if _text.Count == 0 there's no text. What does x = pX - ev.OfX do?

[BDisp]

The mouse is always grabbed no matter has or not text, until other view that want grab the mouse or set focus. It's the offset from current mouse position and the the TextField position. It can be positive or negative, which will give the number of columns that was ofsete to the right or the left.

[tig]

The mouse is always grabbed no matter has or not text, until other view that want grab the mouse or set focus. It's the offset from current mouse position and the the TextField position. It can be positive or negative, which will give the number of columns that was ofsete to the right or the left.

Sorry, that's not answering my question. What is the purpose of the - ev.OfX in this particular case. I fail to see how it can have any impact on anything.

[BDisp]

If I remember is the offset of the current mouse position that is over another view than the grabbed view and the grabbed view itself. Is more and less that. But if you can change the text selected moving the mouse outside the TextView without using OfX/OfY it mean that is not more necessary.

[tig]

In

• Fixes #3273. Updates FindDeepestView to support Adornment #3278

I have revamped this API.

MouseEvent now has this member, replacing OfX/Y:

    /// <summary>
    ///     The screen-relative mouse position.
    /// </summary>
    /// <remarks>
    ///     <para>
    ///         The <see cref="X"/> and <see cref="Y"/> properties are always <see cref="View.Bounds"/>-relative. When the mouse is grabbed by a view,
    ///         <see cref="ScreenPosition"/> provides the mouse position screen-relative coordinates, enabling the grabbed view to know how much the
    ///         mouse has moved.
    ///     </para>
    ///     <para>
    ///         Calculated and processed in <see cref="Application.OnMouseEvent(MouseEventEventArgs)"/>.
    ///     </para>
    /// </remarks>
    public Point ScreenPosition { get; set; }

The only View-derived code (other than Adornment) that uses this is Menu.cs.

[dodexahedron]

Late to this party, but my understanding of it was always that it was for relative positioning, sorta like how jQueryUI does various position-related operations.

If you treat it fluently, and only use it in the appropriate situation (which isn't an appropriate concept in a statically typed language like C#), you get a sentence like "this event happened ev.[Of]X and ev.[Of]Y to the (left, right, top, bottom) of what its parent is relative to."

It makes no sense for it to be there when it isn't in use, which just makes it a bad concept anyway, since it creates rules that the language cannot enforce.

I am a fan of your solution of just no-nonsense position reporting. 👍