javafx.scene.input.*Event classes construction

[Martin Sladecek]

Hi,
here's my proposal for new constructors and methods for events in 
javafx.scene.input package (for 3.0)

I changed all impl_*event factory methods to constructors and added a 
variant with (Object source, EventTarget target, ...), as Event, 
InputEvent, GestureEvent already had such constructors as part of public 
API. Usually, these constructors are used only when the target (or 
source) is known, so no copies must be made during the event dispatch 
process.

Because Event has a "copyFor" method that returns a copy of the current 
object, changing some properties to the values passed in, I used the 
same pattern for all the impl_copy methods. I also added copyFor(Object 
source, EvenTarget target, EventType type) to events that have multiple 
types.

Regarding the rest of @treatAsPrivate methods, I think all of them may 
be part of public API, as they don't expose any internal information or 
structures.

I also made most of the classes final.

*ContextMenuEvent*:

  * public ContextMenuEvent(Object source, EventTarget target,
    EventType<ContextMenuEvent> eventType, double x, double y, double
    screenX, double screenY, boolean keyboardTrigger)
  * public ContextMenuEvent(EventType<ContextMenuEvent> eventType,
    double x, double y, double screenX, double screenY, boolean
    keyboardTrigger)


*DragEvent*:

  * public DragEvent(Object source, EventTarget target,
    EventType<DragEvent> eventType, Dragboard dragboard, double x,
    double y, double screenX, double screenY, TransferMode transferMode,
    Object gestureSource, Object gestureTarget)
  * public DragEvent(EventType<DragEvent> eventType, Dragboard
    dragboard,double x, double y, double screenX, double screenY,
    TransferMode transferMode, Object gestureSource, Object gestureTarget)

  * public DragEvent copyFor(Object source, EventTarget target, Object
    gestureSource, Object gestureTarget, Dragboard dragboard)
  * public DragEvent copyFor(Object source, EventTarget target, Object
    gestureSource, Object gestureTarget, EventType<DragEvent> eventType)
  * public DragEvent copyFor(Object source, EventTarget target, Object
    gestureSource, Object gestureTarget, TransferMode transferMode,
    EventType<DragEvent> eventType)
  * public DragEvent copyFor(Object newSource, EventTarget newTarget,
    EventType<DragEvent> type)
  * public Object getAcceptingObject() // source that accepted the drag


*GestureEvent*: (there were 2  protected constructors that were creating 
empty events, I'd like to make them deprecated)

  * protected GestureEvent(Object source, EventTarget target,
    EventType<? extends GestureEvent> eventType, double x, double y,
    double screenX, double screenY, boolean shiftDown, boolean
    controlDown, boolean altDown, boolean metaDown, boolean direct,
    boolean inertia)
  * protected GestureEvent(EventType<? extends GestureEvent> eventType,
    double x, double y, double screenX, double screenY, boolean
    shiftDown, boolean controlDown, boolean altDown, boolean metaDown,
    boolean direct, boolean inertia)


*InputMethodEvent*:

  * public InputMethodEvent(Object source, EventTarget target,
    EventType<InputMethodEvent> eventType, List<InputMethodTextRun>
    composed, String committed, int caretPosition)


*InputMethodTextRun*:

  * public InputMethodTextRun(String text, InputMethodHighlight highlight)


*KeyEvent*:

  * public KeyEvent(Object source, EventTarget target,
    EventType<KeyEvent> eventType, String character, String text, int
    code, boolean shiftDown, boolean controlDown, boolean altDown,
    boolean metaDown)
  * public KeyEvent(EventType<KeyEvent> eventType, String character,
    String text, int code, boolean shiftDown, boolean controlDown,
    boolean altDown, boolean metaDown)
  * public KeyEvent(EventType<KeyEvent> eventType, String character,
    String text, KeyCode code, boolean shiftDown, boolean controlDown,
    boolean altDown, boolean metaDown)

  * public KeyEvent copyFor(Object newSource, EventTarget newTarget,
    EventType<KeyEvent> type)


*MouseEvent*:

  * public MouseEvent(EventType<? extends MouseEvent> eventType, double
    x, double y, double screenX, double screenY, MouseButton button,int
    clickCount, boolean shiftDown, boolean controlDown, boolean altDown,
    boolean metaDown,  boolean primaryButtonDown, boolean
    middleButtonDown, boolean secondaryButtonDown, boolean synthesized,
    boolean popupTrigger)
  * public MouseEvent(EventType<? extends MouseEvent> eventType, double
    x, double y, double screenX, double screenY, MouseButton button,int
    clickCount, boolean shiftDown, boolean controlDown, boolean altDown,
    boolean metaDown,  boolean primaryButtonDown, boolean
    middleButtonDown, boolean secondaryButtonDown, boolean synthesized,
    boolean popupTrigger, boolean stillSincePress)
  * public MouseEvent(Object source, EventTarget target, EventType<?
    extends MouseEvent> eventType, double x, double y, double screenX,
    double screenY, MouseButton button,int clickCount, boolean
    shiftDown, boolean controlDown, boolean altDown, boolean metaDown, 
    boolean primaryButtonDown, boolean middleButtonDown, boolean
    secondaryButtonDown, boolean synthesized, boolean popupTrigger,
    boolean stillSincePress)

  * public MouseEvent copyFor(Object newSource, EventTarget newTarget,
    EventType<? extends MouseEvent> type)
  * public boolean isPopupTrigger() //This was impl_ before, but it's
    used in some controls, so it might be useful

  * public static MouseDragEvent copyForMouseDragEvent(MouseEvent e,
    Object newSource, EventTarget newTarget, EventType<MouseDragEvent>
    type, Object gestureSource) // this will do a copy of mouse event,
    creating a mouseDragEvent from it. It's used internally and it's
    just a convenience, so can it doesn't have to be added at all to the
    public API


*MouseDragEvent*:

  * public MouseDragEvent(Object source, EventTarget target,
    EventType<MouseDragEvent> eventType, double x, double y, double
    screenX, double screenY,  MouseButton button, int clickCount, 
    boolean shiftDown, boolean controlDown, boolean altDown, boolean
    metaDown,  boolean primaryButtonDown, boolean middleButtonDown,
    boolean secondaryButtonDown, boolean synthesized, boolean
    popupTrigger, Object gestureSource)
  * public MouseDragEvent( EventType<MouseDragEvent> eventType, double
    x, double y, double screenX, double screenY,  MouseButton button,
    int clickCount,  boolean shiftDown, boolean controlDown, boolean
    altDown, boolean metaDown,  boolean primaryButtonDown, boolean
    middleButtonDown, boolean secondaryButtonDown, boolean synthesized,
    boolean popupTrigger, Object gestureSource)

*RotateEvent*:

  * public RotateEvent(Object source, EventTarget target,
    EventType<RotateEvent> eventType, double x, double y, double
    screenX, double screenY, boolean shiftDown, boolean controlDown, 
    boolean altDown,  boolean metaDown, boolean direct, boolean inertia,
    double angle, double totalAngle)
  * public RotateEvent(EventType<RotateEvent> eventType, double x,
    double y, double screenX, double screenY, boolean shiftDown, boolean
    controlDown,  boolean altDown,  boolean metaDown, boolean direct,
    boolean inertia, double angle, double totalAngle)

  * public RotateEvent copyFor(Object newSource, EventTarget newTarget,
    EventType<RotateEvent> type)


*ScrollEvent*:

  * public ScrollEvent(Object source, EventTarget target,
    EventType<ScrollEvent> eventType, double x, double y, double
    screenX, double screenY,  boolean shiftDown,  boolean controlDown,
    boolean altDown,  boolean metaDown, boolean direct,  boolean
    inertia, double deltaX, double deltaY, double gestureDeltaX, double
    gestureDeltaY, HorizontalTextScrollUnits textDeltaXUnits, double
    textDeltaX, VerticalTextScrollUnits textDeltaYUnits, double
    textDeltaY, int touchCount)
  * public ScrollEvent(EventType<ScrollEvent> eventType, double x,
    double y, double screenX, double screenY,  boolean shiftDown, 
    boolean controlDown, boolean altDown,  boolean metaDown, boolean
    direct,  boolean inertia, double deltaX, double deltaY, double
    gestureDeltaX, double gestureDeltaY, HorizontalTextScrollUnits
    textDeltaXUnits, double textDeltaX, VerticalTextScrollUnits
    textDeltaYUnits, double textDeltaY, int touchCount)


  * public ScrollEvent copyFor(Object newSource, EventTarget newTarget,
    EventType<ScrollEvent> type)


*SwipeEvent*:

  * public SwipeEvent(Object source, EventTarget target,
    EventType<SwipeEvent> eventType, double x, double y, double screenX,
    double screenY, boolean shiftDown,  boolean controlDown, boolean
    altDown, boolean metaDown, boolean direct, int touchCount)
  * public SwipeEvent(EventType<SwipeEvent> eventType, double x, double
    y, double screenX, double screenY, boolean shiftDown,  boolean
    controlDown, boolean altDown, boolean metaDown, boolean direct, int
    touchCount)


  * public SwipeEvent copyFor(Object newSource, EventTarget newTarget,
    EventType<SwipeEvent> type)


*ZoomEvent*:

  * public ZoomEvent(Object source, EventTarget target,
    EventType<ZoomEvent> eventType, double x, double y, double screenX,
    double screenY, boolean shiftDown, boolean controlDown, boolean
    altDown, boolean metaDown,  boolean direct, boolean inertia, double
    zoomFactor, double totalZoomFactor)
  * public ZoomEvent(EventType<ZoomEvent> eventType, double x, double y,
    double screenX, double screenY, boolean shiftDown, boolean
    controlDown, boolean altDown, boolean metaDown,  boolean direct,
    boolean inertia, double zoomFactor, double totalZoomFactor)

  * public ZoomEvent copyFor(Object newSource, EventTarget newTarget,
    EventType<ZoomEvent> type)


*TouchEvent*:

  * public TouchEvent(Object source, EventTarget target,
    EventType<TouchEvent> eventType, TouchPoint touchPoint,
    List<TouchPoint> touchPoints, int eventSetId, boolean shiftDown,
    boolean controlDown, boolean altDown,  boolean metaDown, boolean direct)
  * public TouchEvent(EventType<TouchEvent> eventType, TouchPoint
    touchPoint, List<TouchPoint> touchPoints, int eventSetId, boolean
    shiftDown, boolean controlDown, boolean altDown,  boolean metaDown,
    boolean direct)

  * public TouchEvent copyFor(Object newSource, EventTarget newTarget,
    EventType<TouchEvent> type)
  * public boolean isDirect() // was impl_ because (according to a
    comment in code) there are no indirect events yet, but GestureEvent
    already has this public.

*javafx.stage.WindowEvent*:

  * public WindowEvent copyFor(Object newSource, EventTarget newTarget,
    EventType<WindowEvent> type)


-Martin

On 06/15/2012 11:44 PM, Richard Bair wrote:
>>> As for the approach, I think you do the constructors with all params (since events are immutable you have no choice really -- static factory or constructor and I prefer in this case a constructor) + builder (auto generated).
>> And what do you think about impl_copy methods? Personally I think we should remove them completely and turn them to some internal utility methods.
> My initial thought was a copy constructor.
>
>> Also, some events are not 100% immutable, as they are modified during the Scene processing through some impl_methods, like MouseEvent.impl_setClickParam. We'd either need to make some/all of the Event fields protected and do this modifications through subclasses or create some "accessor" in javafx.scene.input package for calling these methods from javafx.scene package.
> Good question, I guess we can revisit these in context of the other impl_ method removal things we're working on.
>
> Richard