org.safs.selenium.util

Class DocumentClickCapture

java.lang.Object

org.safs.selenium.util.DocumentClickCapture

All Implemented Interfaces:

java.lang.Runnable

public class DocumentClickCapture
extends java.lang.Object
implements java.lang.Runnable

Used to intercept mouseup, mousedown, and click events at the DOM document level in order to allow clicks on the document that will NOT invoke the application's event handlers. For example, when a ProcessContainer tool wants to investigate element properties by selecting an element with a click.

Usage:

 DocumentClickCapture listener = new DocumentClickCapture();
 try{
     MouseEvent event = listener.waitForClick(timeout_in_seconds);
     // do stuff with event info
     // use again if desired
     event = listener.waitForClick(timeout_in_seconds);
     // do stuff with event info
 }catch(Exception x){
     // handle them here
 }
 

The use CAN allow the application's event handlers to see the events if the alternate constructor is used setting the allowPropogation boolean to true:

Usage:

 DocumentClickCapture listener = new DocumentClickCapture(true);
 try{
     MouseEvent event = listener.waitForClick(timeout_in_seconds);
     // do stuff with event info
     // use again if desired
     event = listener.waitForClick(timeout_in_seconds);
     // do stuff with event info
 }catch(Exception x){
     // handle them here
 }
 

Author:

Carl Nagle

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_DELAY_WAIT_READY_LOOP in a loop, default delay time (in milliseconds) to sleep before trying to detect the click event-ready (event information has be retrieved from page by javascript) another time.
static boolean	DEFAULT_IGNORE_EVENT_INFORMATION true, will not retrieve event's information.
static int	DEFAULT_TIMEOUT_BETWEEN_EVENT_FIRE_AND_READY After event-fired, default timeout (5000 milliseconds) before click event-ready (event information has be retrieved from page by javascript).
static int	delayWaitReady in a loop, time (in milliseconds) to sleep before trying to detect the click event-ready (event information has be retrieved from page by javascript) another time.
static boolean	ENABLE_CLICK_CAPTURE This field could be used to turn on/off the DocumentClickCapture. This field will ONLY affect the new instance of DocumentClickCapture.
static java.lang.String	LISTENER_ID_ROOT "safs_clickcapture"
static int	LISTENER_LOOP_DELAY in a loop, time (in milliseconds) to sleep before trying to detect the click event-fired on page another time.
static int	timeoutBtwEvtFireAndReady Only eventFired is set to true, this field will take effect. after event-fired, in a loop, timeout (in milliseconds) before click event-ready (event information has be retrieved from page by javascript).

Constructor Summary

Constructors

Constructor and Description
DocumentClickCapture() Default constructor.
DocumentClickCapture(boolean allowPropogation) Alternate constructor.
DocumentClickCapture(boolean allowPropogation, org.openqa.selenium.WebElement target) Alternate constructor.

Method Summary

Modifier and Type	Method and Description
(package private) java.lang.String	_addEventListeners() Attach event-listeners to a target.
(package private) java.lang.String	_removeEventListeners() Remove the attached event-listeners from a target.
void	addListeners(boolean startListening) Inject the Document level event listeners if they are not already injected. Does nothing if the listeners are already injected. This method will also start the polling thread to watch the javascript variable used to monitor 'click event' if it is called with parameter true.
java.lang.String	getListenerID()
boolean	isEnlargeListeningArea() If true, we will use the document as the click-event-receiver. If false, we will use the specific component as the click-event-receiver.
static boolean	isIgnoreEventInformation() get ignoreEventInformation.
void	run() Internal Runnable use only.
void	setEnabled(boolean enabled) Enable or disable the ClickCapture. It must be called before calling startListening().
void	setEnlargeListeningArea(boolean enlargeListeningArea) This should be called before calling startListening(), if we want enlargeListeningArea works as expected.
static void	setIgnoreEventInformation(boolean ignoreEventInformation) set ignoreEventInformation.
void	startListening() Start the polling thread to watch the javascript variable used to monitor 'click event'. Before starting the polling thread, this listener will be disabled if the JavaScript "Alert" is present. This method should be called after calling addListeners(boolean) (addListeners() is called with false). The following is an example:
void	stopListening() Stop the pollingThread from listening and remove the listeners.
MouseEvent	waitForClick(long secondsTimeout)

Methods inherited from class java.lang.Object

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

Field Detail

LISTENER_ID_ROOT

public static final java.lang.String LISTENER_ID_ROOT

"safs_clickcapture"

See Also:

Constant Field Values

LISTENER_LOOP_DELAY

public static int LISTENER_LOOP_DELAY

in a loop, time (in milliseconds) to sleep before trying to detect the click event-fired on page another time.

DEFAULT_TIMEOUT_BETWEEN_EVENT_FIRE_AND_READY

public static final int DEFAULT_TIMEOUT_BETWEEN_EVENT_FIRE_AND_READY

After event-fired, default timeout (5000 milliseconds) before click event-ready (event information has be retrieved from page by javascript).

See Also:

timeoutBtwEvtFireAndReady, Constant Field Values

DEFAULT_DELAY_WAIT_READY_LOOP

public static final int DEFAULT_DELAY_WAIT_READY_LOOP

in a loop, default delay time (in milliseconds) to sleep before trying to detect the click event-ready (event information has be retrieved from page by javascript) another time.

See Also:

Constant Field Values

timeoutBtwEvtFireAndReady

public static int timeoutBtwEvtFireAndReady

Only eventFired is set to true, this field will take effect.
after event-fired, in a loop, timeout (in milliseconds) before click event-ready (event information has be retrieved from page by javascript).

See Also:

eventFired, waitForClick(long)

delayWaitReady

public static int delayWaitReady

in a loop, time (in milliseconds) to sleep before trying to detect the click event-ready (event information has be retrieved from page by javascript) another time.

See Also:

waitForClick(long)

DEFAULT_IGNORE_EVENT_INFORMATION

public static final boolean DEFAULT_IGNORE_EVENT_INFORMATION

true, will not retrieve event's information.

See Also:

Constant Field Values

ENABLE_CLICK_CAPTURE

public static boolean ENABLE_CLICK_CAPTURE

This field could be used to turn on/off the DocumentClickCapture.
This field will ONLY affect the new instance of DocumentClickCapture. For example:

 DocumentClickCapture.ENABLE_CLICK_CAPTURE = true;
 DocumentClickCapture captureA = new DocumentClickCapture(true, target);

 DocumentClickCapture.ENABLE_CLICK_CAPTURE = false;
 DocumentClickCapture captureB = new DocumentClickCapture(true, target);
 DocumentClickCapture captureC = new DocumentClickCapture(true, target);

 captureA is enabled; while captureB and captureC will be disabled.
 

Constructor Detail

DocumentClickCapture

public DocumentClickCapture()

Default constructor. Capture mousedown, mouseup, and click event and DO NOT allow default operation or propagation of the event to the application.

DocumentClickCapture

public DocumentClickCapture(boolean allowPropogation)

Alternate constructor. Capture mousedown, mouseup, and click event trio. Set allowPropogation = true if we want the final "click" to be handled by the application normally.

See Also:

DocumentClickCapture()

DocumentClickCapture

public DocumentClickCapture(boolean allowPropogation,
                            org.openqa.selenium.WebElement target)

Alternate constructor. Capture mousedown, mouseup, and click event trio. Set allowPropogation = true if we want the final "click" to be handled by the application normally.
The target is the receiver of the event. Only the event happens on the target, the attached listener
will be trrigered; Set target to null, if user wants the window.document to be the event receiver.

See Also:

DocumentClickCapture(boolean)

Method Detail

isIgnoreEventInformation

public static boolean isIgnoreEventInformation()

get ignoreEventInformation.

setIgnoreEventInformation

public static void setIgnoreEventInformation(boolean ignoreEventInformation)

set ignoreEventInformation.

setEnabled

public void setEnabled(boolean enabled)

Enable or disable the ClickCapture.
It must be called before calling startListening().

Parameters:

enabled -

See Also:

startListening(), waitForClick(long)

isEnlargeListeningArea

public boolean isEnlargeListeningArea()

If true, we will use the document as the click-event-receiver.
If false, we will use the specific component as the click-event-receiver.

Returns:

boolean

See Also:

enlargeListeningArea

setEnlargeListeningArea

public void setEnlargeListeningArea(boolean enlargeListeningArea)

This should be called before calling startListening(), if we want
enlargeListeningArea works as expected.

Parameters:

enlargeListeningArea -

See Also:

enlargeListeningArea

addListeners

public void addListeners(boolean startListening)
                  throws SeleniumPlusException

Inject the Document level event listeners if they are not already injected.
Does nothing if the listeners are already injected.
This method will also start the polling thread to watch the javascript variable used to monitor 'click event'
if it is called with parameter true. The example code is listed below:

 DocumentClickCapture listener = new DocumentClickCapture();
 try{

     //Add the listener and start the polling thread automatically.
     listener.addListeners(true);

     //do click action;
     ...

     MouseEvent event = listener.waitForClick(timeout_in_seconds);

 }catch(Exception x){
     // handle them here
 }
 

If the click action may cause JS "Alert" pops up, we should call this methods with parameter false
and start the polling thread by calling startListening() later. The example code is listed below:

 DocumentClickCapture listener = new DocumentClickCapture();
 try{

     //Add the listener
     listener.addListeners(false);

     //do click action;
     ...
     //Start listening
     listener.startListening();

     MouseEvent event = listener.waitForClick(timeout_in_seconds);

 }catch(Exception x){
     // handle them here
 }
 

Parameters:

startListening - boolean, If true, start polling thread automatically; otherwise, will not start it and user needs to start it by calling startListening().

Throws:

SeleniumPlusException

See Also:

waitForClick(long), addEventListeners()

startListening

public void startListening()

Start the polling thread to watch the javascript variable used to monitor 'click event'.
Before starting the polling thread, this listener will be disabled if the JavaScript "Alert" is present.
This method should be called after calling addListeners(boolean) (addListeners() is called with false).
The following is an example:

 DocumentClickCapture listener = new DocumentClickCapture();
 try{

     //Add the listener
     listener.addListeners(false);

     //do click action;
     ...
     //Start listening
     listener.startListening();

     MouseEvent event = listener.waitForClick(timeout_in_seconds);

 }catch(Exception x){
     // handle them here
 }
 

See Also:

addListeners(boolean)

stopListening

public void stopListening()

Stop the pollingThread from listening and remove the listeners. Normally only called if waitForClick is going to be bypassed for some reason.

waitForClick

public MouseEvent waitForClick(long secondsTimeout)
                        throws java.lang.IllegalArgumentException,
                               java.lang.InterruptedException,
                               SeleniumPlusException

Parameters:

secondsTimeout - -- timeout in seconds before throwing InterruptedException

Returns:

MouseEvent object with some or all of its fields filled in. Fields can be null.

Throws:

java.lang.InterruptedException - if timeout has been reached.

java.lang.IllegalArgumentException - if secondsTimeout is < 1.

SeleniumPlusException - if we could not add or remove eventListeners in the browser.

See Also:

addListeners(boolean)

run

public void run()

Internal Runnable use only.

This thread monitors the javascript event flag to be set indicating the event was fired. monitor loop can be stopped internally with setRunning(false). If the event is detected the onEventFired() method is invoked by this thread. This is a single-fire event. Once fired or stopped the monitor will exit and the remote EventListeners will be removed from the EventTarget.

Specified by:

run in interface java.lang.Runnable

getListenerID

public java.lang.String getListenerID()

_addEventListeners

java.lang.String _addEventListeners()

Attach event-listeners to a target.

Parameters:

domelement - (Javascript) Object, the dom-element to attach the event-listeners.

See Also:

addEventListeners()

_removeEventListeners

java.lang.String _removeEventListeners()

Remove the attached event-listeners from a target.

Parameters:

domelement - (Javascript) Object, the dom-element to detach the event-listeners.

See Also:

removeEventListeners()