//
// Copyright (c) 2009, Brian Frank and Andy Frank
// Licensed under the Academic Free License version 3.0
//
// History:
//   25 Feb 2009  Andy Frank  Creation
//    8 Jul 2009  Andy Frank  Split webappClient into sys/dom
//    2 Jun 2011  Andy Frank  Rename to DomEvent
//   26 Aug 2015  Andy Frank  Rename back to Event
//

using graphics

**
** Event models the DOM event object.
**
** Common event types:
**
**   "mousedown"   Fired when a mouse button is pressed on an element.
**
**   "mouseup"     Fired when a mouse button is released over an element.
**
**   "click"       Fired when a mouse button is pressed and released on a
**                 single element.
**
**   "mousedown"   Fired when a mouse button is pressed on an element.
**
**   "mouseup"     Fired when a mouse button is released over an element.
**
**   "click"       Fired when a mouse button is pressed and released on a
**                 single element.
**
**   "dblclick"    Fired when a mouse button is clicked twice on a single element.
**
**   "mousemove"   Fired when a mouse is moved while over an element.
**
**   "mouseover"   Fired when mouse is moved onto the element that has the
**                 listener attached or onto one of its children.
**
**   "mouseout"    Fired when mouse is moved off the element that has the
**                 listener attached or off one of its children.
**
**   "mouseenter"  Fired when mouse is moved over the element that has the
**                 listener attached. Similar to '"mouseover"', it differs in
**                 that it doesn't bubble and that it isn't sent when the mouse
**                 is moved from one of its descendants' physical space to its
**                 own physical space.
**
**                 With deep hierarchies, the amount of mouseenter events sent
**                 can be quite huge and cause significant performance problems.
**                 In such cases, it is better to listen for "mouseover" events.
**
**   "mouseleave"  Fired when mouse is moved off the element that has the
**                 listener attached. Similar to "mouseout", it differs in that
**                 it doesn't bubble and that it isn't sent until the pointer
**                 has moved from its physical space and the one of all its
**                 descendants.
**
**                 With deep hierarchies, the amount of mouseleave events sent
**                 can be quite huge and cause significant performance problems.
**                 In such cases, it is better to listen for "mouseout" events.
**
**   "contextmenu" Fired when the right button of the mouse is clicked (before
**                 the context menu is displayed), or when the context menu key
**                 is pressed (in which case the context menu is displayed at the
**                 bottom left of the focused element, unless the element is a
**                 tree, in which case the context menu is displayed at the
**                 bottom left of the current row).
**
**
**   "focus"       The focus event is fired when an element has received focus
**
**   "blur"        The blur event is fired when an element has lost focus.
**
**   "keydown"     Fired when a key is pressed down.
**
**   "keyup"       Fired when a key is released.
**
**   "keypress"    Fired when a key is pressed down and that key normally
**                 produces a character value (use "input" instead).
**
**   "input"       Fired synchronously when the value of an <input> or
**                 <textarea> element is changed.
**
**   "dragstart"   Fired on an element when a drag is started. The user is
**                 requesting to drag the element where the dragstart event is
**                 fired. During this event, a listener would set information
**                 such as the drag data and image to be associated with the drag.
**                 This event is not fired when dragging a file into the browser
**                 from the OS.
**
**   "dragenter"   Fired when the mouse enters an element while a drag is
**                 occurring. A listener for this event should indicate whether
**                 a drop is allowed over this location. If there are no listeners,
**                 or the listeners perform no operations, then a drop is not
**                 allowed by default. This is also the event to listen for in
**                 order to provide feedback that a drop is allowed, such as
**                 displaying a highlight or insertion marker.
**
**   "dragover"    This event is fired as the mouse is moving over an element
**                 when a drag is occurring. Much of the time, the operation that
**                 occurs during a listener will be the same as the "dragenter"
**                 event.
**
**   "dragleave"   This event is fired when the mouse leaves an element while a
**                 drag is occurring. Listeners should remove any highlighting
**                 or insertion markers used for drop feedback.
**
**   "drag"        This event is fired at the source of the drag and is the element
**                 where "dragstart" was fired during the drag operation.
**
**   "drop"        The drop event is fired on the element where the drop
**                 occurred at the end of the drag operation. A listener would
**                 be responsible for retrieving the data being dragged and
**                 inserting it at the drop location. This event will only fire
**                 if a drop is desired. It will not fire if the user cancelled
**                 the drag operation, for example by pressing the Escape key,
**                 or if the mouse button was released while the mouse was not
**                 over a valid drop target.
**
**   "dragend"     The source of the drag will receive a "dragend" event when the
**                 drag operation is complete, whether it was successful or not.
**                 This event is not fired when dragging a file into the browser
**                 from the OS.
**
@Js
class Event
{

//////////////////////////////////////////////////////////////////////////
// Constructors
//////////////////////////////////////////////////////////////////////////

  private new make() {}

//////////////////////////////////////////////////////////////////////////
// Methods
//////////////////////////////////////////////////////////////////////////

  ** The type of this event.
  native Str type()

  ** The target to which the event was dispatched.
  native Elem target()

  ** The mouse position of this event relative to page.
  native Point pagePos()

  ** Return true if the ALT key was pressed during the event.
  native Bool alt()

  ** Return true if the CTRL key was pressed during the event.
  native Bool ctrl()

  ** Return true if the SHIFT key was pressed during the event.
  native Bool shift()

  ** Return true if the Meta key was pressed during the event.  On Macs
  ** this maps to "command" key.  On Windows this maps to "Windows" key.
  native Bool meta()

  ** Mouse button number pressed.
  native Int? button()

  ** Scroll amount for wheel events.
  native Point? delta()

  ** Key instance for key pressed.
  native Key? key()

  ** Err instance if available for 'window.onerror'.
  native Err? err()

  ** Stop further propagation of this event.
  native Void stop()

  ** Get an attribute by name.  If not found return
  ** the specificed default value.
  @Operator native Obj? get(Str name, Obj? def := null)

  ** Set an attribute to the given value.
  @Operator native Void set(Str name, Obj? val)

  ** Get or set an attribute.
  override Obj? trap(Str name, Obj?[]? args := null)
  {
    if (args == null || args.isEmpty) return get(name)
    set(name, args.first)
    return null
  }

  ** The DataTransfer object for this event.
  native DataTransfer dataTransfer()

  ** Meta-data for this event instance.
  Str:Obj? stash := Str:Obj?[:]

  override Str toStr()
  {
    "Event { type=$type target=$target pagePos=$pagePos button=$button delta=$delta key=$key" +
    " alt="   + (alt   ? "T" : "F") +
    " ctrl="  + (ctrl  ? "T" : "F") +
    " shift=" + (shift ? "T" : "F") +
    " meta="  + (meta  ? "T" : "F") +
    " }"
  }
}