Package com.smartgwt.client.tools.stream

# Class EventStream

java.lang.Object
com.smartgwt.client.core.BaseClass
com.smartgwt.client.tools.stream.EventStream

All Implemented Interfaces:
  `HasHandlers`

public class EventStream extends BaseClass
Note: this is currently an experimental feature and not covered by normal support guarantees. See `Experimental Features` for more information.
A `EventStream` captures event details as JavaScript objects as they are handled by the `EventHandler`. The event target `canvas` ID and class name as well the `locator` are included, as available. Event-specific data (for example, the String for keyboard events) are also included where appropriate. See `EventStreamEvent` for more information.

You can configure the stream to capture most DOM event types and other useful events, such as `relogins` and JavaScript errors that are triggered by events:

Event Category | Includes (source DOM eventType(s) or description) | Controlling Attribute | From DOM Event?
--- | --- | --- | ---
click events | `mouseDown`, `mouseUp`, `click`, `dblClick` | `captureClickEvents` | Y
move events | `mouseMove`, `mouseOut` | `captureMoveEvents` | Y
key events | `keyDown`, `keyPress`, `keyUp` | `captureKeyEvents` | Y
drag events | `dragStart`, `dragMove`, `dragStop` | `captureDragEvents` | Y
context menu events | `contextMenu` | `captureMenuEvents` | Y
mouse wheel events | `mouseWheel` | `captureWheelEvents` | Y
page events | `load`, `unload`, `resize` | `capturePageEvents` | Y
login events | Successful `relogin` via the `RPCManager` | `captureLoginEvents` | N
`Reify` file events | Project and screen (auto)saves and loads | `captureDSFileEvents` | N
event errors | JavaScript exceptions | `captureEventErrors` | N

(Pointer and touch equivalents to mouse events have not been listed above. See the associated attribute for a more inclusive list.)

Note that several types of DOM events can be collapsed so that one event is reported instead of many if they occur over the same target. You can enable collapsing for `move and drag events`, `key events`, `wheel events`, and `page events`. A `stream capture limit` is also supported via circular buffering, so that only the most recent events are preserved. All available events can be returned as an array of `EventStreamEvent` via `getEvents()`.

A `EventStream` will start capturing events as soon as it's created by default, but if you set `autoStart`: false, you can start capturing manually by calling `start()`. Calling `end()` will end capturing and return the `EventStreamData`.

See Also:
  - `EventHandler`
  - `RPCManager`
  - `Reify Overview`
  - `Experimental Features`

- ## Field Summary

  ### Fields inherited from class com.smartgwt.client.core.BaseClass

  `config, configOnly, factoryCreated, factoryProperties, id, scClassName`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `EventStream()`
  `EventStream(JavaScriptObject jsObj)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `JavaScriptObject`
  `create()`
  `EventStreamData`
  `end()`
  Ends event capturing and returns the `EventStreamData`.
  `SeleniumCommand[]`
  `getAsSeleneseCommands()`
  Creates and returns Selenese that represents the events captured by the stream as an array of `Selenium commands`.
  `SeleniumCommand[]`
  `getAsSeleneseCommands(SeleneseSettings settings)`
  Creates and returns Selenese that represents the events captured by the stream as an array of `Selenium commands`.
  `String`
  `getAsSeleneseHTML()`
  Creates and returns Selenese that represents the events captured by the stream.
  `String`
  `getAsSeleneseHTML(SeleneseSettings settings)`
  Creates and returns Selenese that represents the events captured by the stream.
  `boolean`
  `getAutoStart()`
  Whether the stream should automatically begin capturing events.
  `boolean`
  `getCaptureClickEvents()`
  Whether mouse button-driven events (or their touch equivalents) should be captured by the stream.
  `boolean`
  `getCaptureDragEvents()`
  Whether dragging-related events should be captured by the stream.
  `boolean`
  `getCaptureEventErrors()`
  Whether to capture JavaScript errors.
  `boolean`
  `getCaptureKeyEvents()`
  Whether keyboard input events should be captured by the stream.
  `boolean`
  `getCaptureLoginEvents()`
  Whether `relogin`s are captured by the stream.
  `boolean`
  `getCaptureMenuEvents()`
  Whether opening a context menu should be captured by the stream.
  `boolean`
  `getCaptureMoveEvents()`
  Whether mouse or touch motion-related events (other than dragging) should be captured by the stream.
  `boolean`
  `getCapturePageEvents()`
  Whether page-level events such as a page load or resize should be captured by the stream.
  `boolean`
  `getCaptureWheelEvents()`
  Whether mouse wheel events should be captured by the stream.
  `boolean`
  `getCollapseKeyEvents()`
  Whether to collapse adjacent `keyPress` events into one event where possible.
  `boolean`
  `getCollapseMoveEvents()`
  Whether mouse or touch-motion related events (including dragging) with the same `eventType` and `targetID` should be collapsed into a single event.
  `boolean`
  `getCollapsePageEvents()`
  Whether adjacgent page events with the same `eventType` should be collapsed into a single event.
  `boolean`
  `getCollapseWheelEvents()`
  Whether mouse wheel events with the same `targetID` and scroll directions should be collapsed into a single event, containing a sum of the `delta offsets` from the original events.
  `EventStreamEvent[]`
  `getEvents()`
  Returns all available captured events, oldest first.
  `JavaScriptObject`
  `getJsObj()`
  `Integer`
  `getMaxSize()`
  Maximum number of events that will be stored by this `EventStream`.
  `int`
  `getMinErrorReportingInterval()`
  Number of seconds that must elapse before another event error will be reported.
  `JavaScriptObject`
  `getOrCreateJsObj()`
  `static EventStream`
  `getOrCreateRef(JavaScriptObject jsObj)`
  `Date`
  `getStartTime()`
  Returns when this stream started capturing events (i.e.
  `boolean`
  `isCreated()`
  `EventStream`
  `setAutoStart(boolean autoStart)`
  Whether the stream should automatically begin capturing events.
  `EventStream`
  `setCaptureClickEvents(boolean captureClickEvents)`
  Whether mouse button-driven events (or their touch equivalents) should be captured by the stream.
  `EventStream`
  `setCaptureDragEvents(boolean captureDragEvents)`
  Whether dragging-related events should be captured by the stream.
  `EventStream`
  `setCaptureEventErrors(boolean captureEventErrors)`
  Whether to capture JavaScript errors.
  `EventStream`
  `setCaptureKeyEvents(boolean captureKeyEvents)`
  Whether keyboard input events should be captured by the stream.
  `EventStream`
  `setCaptureLoginEvents(boolean captureLoginEvents)`
  Whether `relogin`s are captured by the stream.
  `EventStream`
  `setCaptureMenuEvents(boolean captureMenuEvents)`
  Whether opening a context menu should be captured by the stream.
  `EventStream`
  `setCaptureMoveEvents(boolean captureMoveEvents)`
  Whether mouse or touch motion-related events (other than dragging) should be captured by the stream.
  `EventStream`
  `setCapturePageEvents(boolean capturePageEvents)`
  Whether page-level events such as a page load or resize should be captured by the stream.
  `EventStream`
  `setCaptureWheelEvents(boolean captureWheelEvents)`
  Whether mouse wheel events should be captured by the stream.
  `EventStream`
  `setCollapseKeyEvents(boolean collapseKeyEvents)`
  Whether to collapse adjacent `keyPress` events into one event where possible.
  `EventStream`
  `setCollapseMoveEvents(boolean collapseMoveEvents)`
  Whether mouse or touch-motion related events (including dragging) with the same `eventType` and `targetID` should be collapsed into a single event.
  `EventStream`
  `setCollapsePageEvents(boolean collapsePageEvents)`
  Whether adjacgent page events with the same `eventType` should be collapsed into a single event.
  `EventStream`
  `setCollapseWheelEvents(boolean collapseWheelEvents)`
  Whether mouse wheel events with the same `targetID` and scroll directions should be collapsed into a single event, containing a sum of the `delta offsets` from the original events.
  `void`
  `setEventErrorListener(EventErrorCallback callback)`
  Installs a callback that will be called when the EventStream reports an `event error`, subject to the `error reporting interval`.
  `void`
  `setJavaScriptObject(JavaScriptObject jsObj)`
  `EventStream`
  `setMaxSize(Integer maxSize)`
  Maximum number of events that will be stored by this `EventStream`.
  `EventStream`
  `setMinErrorReportingInterval(int minErrorReportingInterval)`
  Number of seconds that must elapse before another event error will be reported.
  `void`
  `start()`
  Starts capturing all enabled events.

  ### Methods inherited from class com.smartgwt.client.core.BaseClass

  `addDynamicProperty, addDynamicProperty, addDynamicProperty, addDynamicProperty, applyFactoryProperties, asSGWTComponent, clearDynamicProperty, createJsObj, destroy, doAddHandler, doInit, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsMap, getAttributeAsString, getAttributeAsStringArray, getClassName, getConfig, getHandlerCount, getID, getRef, getRuleScope, getScClassName, getTestInstance, hasAutoAssignedID, hasDynamicProperty, internalSetID, internalSetID, isConfigOnly, isFactoryCreated, onBind, onInit, registerID, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAutoID, setConfig, setConfigOnly, setFactoryCreated, setID, setProperty, setProperty, setProperty, setProperty, setRuleScope, setScClassName`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### EventStream

    public EventStream()

  - ### EventStream

    public EventStream(JavaScriptObject jsObj)

- ## Method Details

  - ### getOrCreateRef

    public static EventStream getOrCreateRef(JavaScriptObject jsObj)

  - ### setJavaScriptObject

    public void setJavaScriptObject(JavaScriptObject jsObj)
    Overrides:
      `setJavaScriptObject` in class `BaseClass`

  - ### create

    public JavaScriptObject create()
    Specified by:
      `create` in class `BaseClass`

  - ### isCreated

    public boolean isCreated()
    Overrides:
      `isCreated` in class `BaseClass`

  - ### getJsObj

    public JavaScriptObject getJsObj()
    Overrides:
      `getJsObj` in class `BaseClass`

  - ### getOrCreateJsObj

    public JavaScriptObject getOrCreateJsObj()
    Overrides:
      `getOrCreateJsObj` in class `BaseClass`

  - ### setAutoStart

    public EventStream setAutoStart(boolean autoStart) throws IllegalStateException
    Whether the stream should automatically begin capturing events. If false, the steam won't start capturing events until `start()` is called.
    Parameters:
      `autoStart` - New autoStart value. Default value is true
    Returns:
      `EventStream` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getAutoStart

    public boolean getAutoStart()
    Whether the stream should automatically begin capturing events. If false, the steam won't start capturing events until `start()` is called.
    Returns:
      Current autoStart value. Default value is true

  - ### setCaptureClickEvents

    public EventStream setCaptureClickEvents(boolean captureClickEvents) throws IllegalStateException
    Whether mouse button-driven events (or their touch equivalents) should be captured by the stream.

    Includes such `eventType`s as `mouseDown`, `mouseUp`, `click`, `doubleClk`, `pointerDown`, `pointerUp`, `pointerCancel`, `touchStart`, `touchEnd`, and `touchCancel`.

    Parameters:
      `captureClickEvents` - New captureClickEvents value. Default value is true
    Returns:
      `EventStream` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getCaptureClickEvents

    public boolean getCaptureClickEvents()
    Whether mouse button-driven events (or their touch equivalents) should be captured by the stream.

    Includes such `eventType`s as `mouseDown`, `mouseUp`, `click`, `doubleClk`, `pointerDown`, `pointerUp`, `pointerCancel`, `touchStart`, `touchEnd`, and `touchCancel`.

    Returns:
      Current captureClickEvents value. Default value is true

  - ### setCaptureDragEvents

    public EventStream setCaptureDragEvents(boolean captureDragEvents) throws IllegalStateException
    Whether dragging-related events should be captured by the stream. Multiple "drag move" type events that have the same `eventType` and `targetID` will be collapsed into one if `collapseMoveEvents` is true.

    Includes such `eventType`s as:

    - `dragStart`, `dragRepositionStart`, `dragResizeStart`, `dragSelectStart`,
    - `dragMove`, `dragRepositionMove`, `dragResizeMove`, `dragSelectMove`,
    - `dragStop`, `dragRepositionStop`, `dragResizeStop`, `dragSelectStop`,
    - `drop`, `dropOver`, and `dragLeave`.
    Parameters:
      `captureDragEvents` - New captureDragEvents value. Default value is true
    Returns:
      `EventStream` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getCaptureDragEvents

    public boolean getCaptureDragEvents()
    Whether dragging-related events should be captured by the stream. Multiple "drag move" type events that have the same `eventType` and `targetID` will be collapsed into one if `collapseMoveEvents` is true.

    Includes such `eventType`s as:

    - `dragStart`, `dragRepositionStart`, `dragResizeStart`, `dragSelectStart`,
    - `dragMove`, `dragRepositionMove`, `dragResizeMove`, `dragSelectMove`,
    - `dragStop`, `dragRepositionStop`, `dragResizeStop`, `dragSelectStop`,
    - `drop`, `dropOver`, and `dragLeave`.
    Returns:
      Current captureDragEvents value. Default value is true

  - ### setCaptureEventErrors

    public EventStream setCaptureEventErrors(boolean captureEventErrors) throws IllegalStateException
    Whether to capture JavaScript errors. If an already-captured event triggered the error, the details will attached to that event. Otherwise, a separate event will be created, with the `eventType` of the last dispatched DOM event (i.e., there is no special "error" `eventType`.)

    `EventStreamEvent` records annotated or specially-reported with error details will contain an `errorTrace` with the error stack trace, and a `threadCode` reporting the thread ID from the `EventHandler` responsible for the error.

    Parameters:
      `captureEventErrors` - New captureEventErrors value. Default value is true
    Returns:
      `EventStream` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getCaptureEventErrors

    public boolean getCaptureEventErrors()
    Whether to capture JavaScript errors. If an already-captured event triggered the error, the details will attached to that event. Otherwise, a separate event will be created, with the `eventType` of the last dispatched DOM event (i.e., there is no special "error" `eventType`.)

    `EventStreamEvent` records annotated or specially-reported with error details will contain an `errorTrace` with the error stack trace, and a `threadCode` reporting the thread ID from the `EventHandler` responsible for the error.

    Returns:
      Current captureEventErrors value. Default value is true

  - ### setCaptureKeyEvents

    public EventStream setCaptureKeyEvents(boolean captureKeyEvents) throws IllegalStateException
    Whether keyboard input events should be captured by the stream. For non-modifier keys, which includes all the self-inserting visible keyboard characters, we capture only the `keyPress`, as `keyDown`/`keyUp` are generally not useful. Conversely, for modifier keys (e.g. Shift), we capture only the `keyDown` and `keyUp`. events, and not the `keyPress`.

    If `collapseKeyEvents` is true, multiple adjacent keyPress events may be collapsed into a single event for greater readability and a more compact event trace.

    Note that if an error is thrown while handling an event, it will get reported regardless of this setting and the above capturing rules, but see `minErrorReportingInterval`. So for example an error handling a `keyDown` would still generally end up in the event trace, even for a self-inserting key such as "A".

    Parameters:
      `captureKeyEvents` - New captureKeyEvents value. Default value is false
    Returns:
      `EventStream` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getCaptureKeyEvents

    public boolean getCaptureKeyEvents()
    Whether keyboard input events should be captured by the stream. For non-modifier keys, which includes all the self-inserting visible keyboard characters, we capture only the `keyPress`, as `keyDown`/`keyUp` are generally not useful. Conversely, for modifier keys (e.g. Shift), we capture only the `keyDown` and `keyUp`. events, and not the `keyPress`.

    If `collapseKeyEvents` is true, multiple adjacent keyPress events may be collapsed into a single event for greater readability and a more compact event trace.

    Note that if an error is thrown while handling an event, it will get reported regardless of this setting and the above capturing rules, but see `minErrorReportingInterval`. So for example an error handling a `keyDown` would still generally end up in the event trace, even for a self-inserting key such as "A".

    Returns:
      Current captureKeyEvents value. Default value is false

  - ### setCaptureLoginEvents

    public EventStream setCaptureLoginEvents(boolean captureLoginEvents) throws IllegalStateException
    Whether `relogin`s are captured by the stream. Login events are non-DOM events originating from the `RPCManager` rather than the `EventHandler`. Login events have a `transaction URL`.

    Includes the `eventType` `relogin`.

    Parameters:
      `captureLoginEvents` - New captureLoginEvents value. Default value is true
    Returns:
      `EventStream` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getCaptureLoginEvents

    public boolean getCaptureLoginEvents()
    Whether `relogin`s are captured by the stream. Login events are non-DOM events originating from the `RPCManager` rather than the `EventHandler`. Login events have a `transaction URL`.

    Includes the `eventType` `relogin`.

    Returns:
      Current captureLoginEvents value. Default value is true

  - ### setCaptureMenuEvents

    public EventStream setCaptureMenuEvents(boolean captureMenuEvents) throws IllegalStateException
    Whether opening a context menu should be captured by the stream. This may occur due to mouse or keyboard interaction.

    Includes the `eventType` `contextMenu`.

    Parameters:
      `captureMenuEvents` - New captureMenuEvents value. Default value is true
    Returns:
      `EventStream` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getCaptureMenuEvents

    public boolean getCaptureMenuEvents()
    Whether opening a context menu should be captured by the stream. This may occur due to mouse or keyboard interaction.

    Includes the `eventType` `contextMenu`.

    Returns:
      Current captureMenuEvents value. Default value is true

  - ### setCaptureMoveEvents

    public EventStream setCaptureMoveEvents(boolean captureMoveEvents) throws IllegalStateException
    Whether mouse or touch motion-related events (other than dragging) should be captured by the stream. Multple adjacent "move events" having the same `eventType` and `targetID` will be collapsed into one if `collapseMoveEvents` is true.

    Includes such `eventType`s as `mouseMove`, `pointerMove`, `touchMove`, and `mouseOut`.

    Parameters:
      `captureMoveEvents` - New captureMoveEvents value. Default value is false
    Returns:
      `EventStream` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getCaptureMoveEvents

    public boolean getCaptureMoveEvents()
    Whether mouse or touch motion-related events (other than dragging) should be captured by the stream. Multple adjacent "move events" having the same `eventType` and `targetID` will be collapsed into one if `collapseMoveEvents` is true.

    Includes such `eventType`s as `mouseMove`, `pointerMove`, `touchMove`, and `mouseOut`.

    Returns:
      Current captureMoveEvents value. Default value is false

  - ### setCapturePageEvents

    public EventStream setCapturePageEvents(boolean capturePageEvents) throws IllegalStateException
    Whether page-level events such as a page load or resize should be captured by the stream. Multple adjacent page events having the same eventType will be collapsed into one if `collapsePageEvents` is true.

    Includes such `eventType`s as `load`, `unload`, and `resize`.

    Parameters:
      `capturePageEvents` - New capturePageEvents value. Default value is false
    Returns:
      `EventStream` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getCapturePageEvents

    public boolean getCapturePageEvents()
    Whether page-level events such as a page load or resize should be captured by the stream. Multple adjacent page events having the same eventType will be collapsed into one if `collapsePageEvents` is true.

    Includes such `eventType`s as `load`, `unload`, and `resize`.

    Returns:
      Current capturePageEvents value. Default value is false

  - ### setCaptureWheelEvents

    public EventStream setCaptureWheelEvents(boolean captureWheelEvents) throws IllegalStateException
    Whether mouse wheel events should be captured by the stream. If the preceding "wheel event" has the same `targetID` and scroll directions, it will be replaced by the current one, subject to `collapseWheelEvents`, with the `delta offsets` in the "collapsed" event getting adjusted to be the sum of those from all the original events.

    Includes the `eventType` `mouseWheel`.

    Parameters:
      `captureWheelEvents` - New captureWheelEvents value. Default value is true
    Returns:
      `EventStream` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getCaptureWheelEvents

    public boolean getCaptureWheelEvents()
    Whether mouse wheel events should be captured by the stream. If the preceding "wheel event" has the same `targetID` and scroll directions, it will be replaced by the current one, subject to `collapseWheelEvents`, with the `delta offsets` in the "collapsed" event getting adjusted to be the sum of those from all the original events.

    Includes the `eventType` `mouseWheel`.

    Returns:
      Current captureWheelEvents value. Default value is true

  - ### setCollapseKeyEvents

    public EventStream setCollapseKeyEvents(boolean collapseKeyEvents) throws IllegalStateException
    Whether to collapse adjacent `keyPress` events into one event where possible. Self-inserting keys will generally be collapsed by concatenating them into a single string, `EventStreamEvent.keyNames`. On the other hand, special keys such as "Esc" and "Backspace" will only be collapsed for repeating sequences of the same key, which will be reported as `EventStreamEvent.count`.

    Note that if an error is thrown while handling an event, it won't be collapsed, but see `minErrorReportingInterval`.

    Parameters:
      `collapseKeyEvents` - New collapseKeyEvents value. Default value is true
    Returns:
      `EventStream` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `setCaptureKeyEvents(boolean)`

  - ### getCollapseKeyEvents

    public boolean getCollapseKeyEvents()
    Whether to collapse adjacent `keyPress` events into one event where possible. Self-inserting keys will generally be collapsed by concatenating them into a single string, `EventStreamEvent.keyNames`. On the other hand, special keys such as "Esc" and "Backspace" will only be collapsed for repeating sequences of the same key, which will be reported as `EventStreamEvent.count`.

    Note that if an error is thrown while handling an event, it won't be collapsed, but see `minErrorReportingInterval`.

    Returns:
      Current collapseKeyEvents value. Default value is true
    See Also:
      - `getCaptureKeyEvents()`

  - ### setCollapseMoveEvents

    public EventStream setCollapseMoveEvents(boolean collapseMoveEvents) throws IllegalStateException
    Whether mouse or touch-motion related events (including dragging) with the same `eventType` and `targetID` should be collapsed into a single event.

    Note that if an error is thrown while handling an event, it won't be collapsed, but see `minErrorReportingInterval`.

    Parameters:
      `collapseMoveEvents` - New collapseMoveEvents value. Default value is true
    Returns:
      `EventStream` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `setCaptureMoveEvents(boolean)`

  - ### getCollapseMoveEvents

    public boolean getCollapseMoveEvents()
    Whether mouse or touch-motion related events (including dragging) with the same `eventType` and `targetID` should be collapsed into a single event.

    Note that if an error is thrown while handling an event, it won't be collapsed, but see `minErrorReportingInterval`.

    Returns:
      Current collapseMoveEvents value. Default value is true
    See Also:
      - `getCaptureMoveEvents()`

  - ### setCollapsePageEvents

    public EventStream setCollapsePageEvents(boolean collapsePageEvents) throws IllegalStateException
    Whether adjacgent page events with the same `eventType` should be collapsed into a single event.

    Note that if an error is thrown while handling an event, it won't be collapsed, but see `minErrorReportingInterval`.

    Parameters:
      `collapsePageEvents` - New collapsePageEvents value. Default value is true
    Returns:
      `EventStream` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `setCapturePageEvents(boolean)`

  - ### getCollapsePageEvents

    public boolean getCollapsePageEvents()
    Whether adjacgent page events with the same `eventType` should be collapsed into a single event.

    Note that if an error is thrown while handling an event, it won't be collapsed, but see `minErrorReportingInterval`.

    Returns:
      Current collapsePageEvents value. Default value is true
    See Also:
      - `getCapturePageEvents()`

  - ### setCollapseWheelEvents

    public EventStream setCollapseWheelEvents(boolean collapseWheelEvents) throws IllegalStateException
    Whether mouse wheel events with the same `targetID` and scroll directions should be collapsed into a single event, containing a sum of the `delta offsets` from the original events.

    Note that if an error is thrown while handling an event, it won't be collapsed, but see `minErrorReportingInterval`.

    Parameters:
      `collapseWheelEvents` - New collapseWheelEvents value. Default value is true
    Returns:
      `EventStream` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `setCaptureWheelEvents(boolean)`

  - ### getCollapseWheelEvents

    public boolean getCollapseWheelEvents()
    Whether mouse wheel events with the same `targetID` and scroll directions should be collapsed into a single event, containing a sum of the `delta offsets` from the original events.

    Note that if an error is thrown while handling an event, it won't be collapsed, but see `minErrorReportingInterval`.

    Returns:
      Current collapseWheelEvents value. Default value is true
    See Also:
      - `getCaptureWheelEvents()`

  - ### setMaxSize

    public EventStream setMaxSize(Integer maxSize) throws IllegalStateException
    Maximum number of events that will be stored by this `EventStream`. After `maxSize` events are captured, the oldest events will be overwritten. Set this property to `null` to capture events without ever overwriting.
    Parameters:
      `maxSize` - New maxSize value. Default value is 10000
    Returns:
      `EventStream` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created

  - ### getMaxSize

    public Integer getMaxSize()
    Maximum number of events that will be stored by this `EventStream`. After `maxSize` events are captured, the oldest events will be overwritten. Set this property to `null` to capture events without ever overwriting.
    Returns:
      Current maxSize value. Default value is 10000

  - ### setMinErrorReportingInterval

    public EventStream setMinErrorReportingInterval(int minErrorReportingInterval) throws IllegalStateException
    Number of seconds that must elapse before another event error will be reported. This allows you to avoid the stream getting flooded with likely duplicate errors that may be rapidly and repeatedly reported, due to mouseMove or repeatedly executing code. Setting the property to zero disables it (avoiding any timestamp checking).

    Note that when an error is reported by the Framework, this property will be ignored if the last captured event triggered the error and has no `errorTrace`, so that it effectively only prevents adding new events to the stream specifically to report errors. However, an `errorTrace` attached to an event within the reporting interval of the previous error won't prevent that event from being `collapsed`.

    Parameters:
      `minErrorReportingInterval` - New minErrorReportingInterval value. Default value is 10
    Returns:
      `EventStream` instance, for chaining setter calls
    Throws:
      `IllegalStateException` - this property cannot be changed after the underlying component has been created
    See Also:
      - `setCollapseMoveEvents(boolean)`
      - `setCollapseKeyEvents(boolean)`
      - `setCollapseWheelEvents(boolean)`
      - `setCollapsePageEvents(boolean)`

  - ### getMinErrorReportingInterval

    public int getMinErrorReportingInterval()
    Number of seconds that must elapse before another event error will be reported. This allows you to avoid the stream getting flooded with likely duplicate errors that may be rapidly and repeatedly reported, due to mouseMove or repeatedly executing code. Setting the property to zero disables it (avoiding any timestamp checking).

    Note that when an error is reported by the Framework, this property will be ignored if the last captured event triggered the error and has no `errorTrace`, so that it effectively only prevents adding new events to the stream specifically to report errors. However, an `errorTrace` attached to an event within the reporting interval of the previous error won't prevent that event from being `collapsed`.

    Returns:
      Current minErrorReportingInterval value. Default value is 10
    See Also:
      - `getCollapseMoveEvents()`
      - `getCollapseKeyEvents()`
      - `getCollapseWheelEvents()`
      - `getCollapsePageEvents()`

  - ### end

    public EventStreamData end()
    Ends event capturing and returns the `EventStreamData`. Once ended, capturing cannot be restarted without losing all stored events.
    Returns:
    See Also:
      - `getAutoStart()`
      - `start()`

  - ### getAsSeleneseCommands

    public SeleniumCommand[] getAsSeleneseCommands()
    Creates and returns Selenese that represents the events captured by the stream as an array of `Selenium commands`. Compare with `getAsSeleneseHTML()`, where you'll also find more common details.

    Just as when retrieving the Selenese as HTML, if a `transformSelenese()` function has been defined, it's called before returning the Selenese.

    Returns:
    See Also:
      - `Automated Testing`

  - ### getAsSeleneseCommands

    public SeleniumCommand[] getAsSeleneseCommands(SeleneseSettings settings)
    Creates and returns Selenese that represents the events captured by the stream as an array of `Selenium commands`. Compare with `getAsSeleneseHTML()`, where you'll also find more common details.

    Just as when retrieving the Selenese as HTML, if a `transformSelenese()` function has been defined, it's called before returning the Selenese.

    Parameters:
      `settings` -
    Returns:
    See Also:
      - `Automated Testing`

  - ### getAsSeleneseHTML

    public String getAsSeleneseHTML()
    Creates and returns Selenese that represents the events captured by the stream. This Selenese contains Smart GWT-specific locators (scLocators), and Smart GWT command extensions (e.g. "waitForElementClickable") that are discussed in our `Selenium` overview.

    This method returns the Selenese as a string of HTML table rows, just as in an rctest.html file that you can directly execute with Selenium. Does not include the leading or trailing HTML, such as the <BODY> and <TBODY> tags; you'll need to wrap what's returned with the appropriate outer HTML tags to properly embed the table. If you'd rather have the Selenese returned as an array of `Selenium commands`, call `getAsSeleneseCommands()` instead.

    To customize the returned Selenese, see `transformSelenese()`. Note that if the stream has `rolled over`, the Selenese for the lost events will not be returned.

    For example, in your `Entrypoint` class definition, you can declare a stream member like:

              EventStream eventStream = new EventStream();

    ... time passes where end user is interacting with your app .... Then to retrieve the Selenese you can call something like:

              String rcTestHTML = "<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">" +
                                  "<body><table><tbody>" +
                                  MyApp.eventStream.getAsSeleneseHTML(true) +
                                  "</tbody></table></body></html>";

    Returns:
      See `HTML`
    See Also:
      - `Automated Testing`

  - ### getAsSeleneseHTML

    public String getAsSeleneseHTML(SeleneseSettings settings)
    Creates and returns Selenese that represents the events captured by the stream. This Selenese contains Smart GWT-specific locators (scLocators), and Smart GWT command extensions (e.g. "waitForElementClickable") that are discussed in our `Selenium` overview.

    This method returns the Selenese as a string of HTML table rows, just as in an rctest.html file that you can directly execute with Selenium. Does not include the leading or trailing HTML, such as the <BODY> and <TBODY> tags; you'll need to wrap what's returned with the appropriate outer HTML tags to properly embed the table. If you'd rather have the Selenese returned as an array of `Selenium commands`, call `getAsSeleneseCommands()` instead.

    To customize the returned Selenese, see `transformSelenese()`. Note that if the stream has `rolled over`, the Selenese for the lost events will not be returned.

    For example, in your `Entrypoint` class definition, you can declare a stream member like:

              EventStream eventStream = new EventStream();

    ... time passes where end user is interacting with your app .... Then to retrieve the Selenese you can call something like:

              String rcTestHTML = "<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">" +
                                  "<body><table><tbody>" +
                                  MyApp.eventStream.getAsSeleneseHTML(true) +
                                  "</tbody></table></body></html>";

    Parameters:
      `settings` -
    Returns:
      See `HTML`
    See Also:
      - `Automated Testing`

  - ### getEvents

    public EventStreamEvent[] getEvents()
    Returns all available captured events, oldest first. At most `maxSize` events will be returned.
    Returns:
    See Also:
      - `end()`

  - ### getStartTime

    public Date getStartTime()
    Returns when this stream started capturing events (i.e. when `start()` got called).
    Returns:
    See Also:
      - `start()`
      - `getAutoStart()`

  - ### setEventErrorListener

    public void setEventErrorListener(EventErrorCallback callback)
    Installs a callback that will be called when the EventStream reports an `event error`, subject to the `error reporting interval`. The callback will be passed all retained `EventStreamEvent`s captured by the stream since the last time it was called.
    Parameters:
      `callback` - Callback to fire when the stream encounters an event error, subject to the reporting interval
    See Also:
      - `getMaxSize()`
      - `getMinErrorReportingInterval()`

  - ### start

    public void start()
    Starts capturing all enabled events. See the overview of `EventStream` for a list of filter properties you can configure to control which events are captured.

    If called after `end()`, capturing will restart, but all previously stored events will be lost.

    See Also:
      - `getAutoStart()`
      - `end()`