Getting rid of the “Gray Box” in PhoneGap for Windows Phone

If you’ve ever used a Windows Phone device’s web browser, then you have probably noticed the gray highlight that the Windows Phone browser puts on top of the HTML content any time that you click on a link. For static web pages, this isn’t a big deal. It indicates that you have clicked on an item. However, if you are building apps with dynamic content, this can become much more frustrating and can have a negative impact in overall user experience.  Fret not, TouchClick.js is here to help!

In PhoneGap applications, you can build experiences that respond to mouse/touch events, which can be more dynamic than what is supported in the device browser. Note: The device browser does not support mouse events. All touch input gets translated into mousedown, mousemove, or mouseup events inside of the PhoneGap container. This gray highlight can become a major pain point in highly-dynamic applications. Luckily, I’ve found a way to get rid of it. Check out the video below to see an example of the gray highlight, as well as the workaround in action:

Through lots of trial and error, I’ve found that the gray highlight is applied to all <a> anchor elements, and any html element that has a “click” event handler or lingering “mousedown” and “mouseup” event handlers.   Luckily, you can manage event listeners and add/remove event handlers as necessary so that you minimize the gray box.  This approach does not get rid of the gray box 100% of the time, but I think it’s safe to say that it gets rid of it 90% of the time.  After applying these techniques, I only see the gray highlight if you tap on multiple clickable items in rapid succession.

Here’s how I was able to get rid of the gray highlight box:

  1. Do not use <a> anchor tags ever.
  2. Assign a “mousedown” event handler to the <span>, <div> or other element that you want to be clickable.
  3. When the “mousedown” event handler is invoked, remove the “mousedown” event handler, save the mousedown input coordinates, and add a “mouseup” event handler to the window object.
  4. When the “mouseup” event handler is invoked, remove the “mouseup” event handler, and then compare the mouse coordinates. If the mouse coordinates have not changed, and its within a reasonable amount of time, you can infer that this should be a “click” event, and invoke an action as desired.
  5. Set a timeout to restore the “mousedown” event handler in an asynchronus operation.   If you re-add the “mousedown” event handler inside of the “mouseup” event handler, you will still get the gray box.

To make things even more confusing, if you have dynamic content (changing DOM elements) underneath of your touch input, then you get multiple mousedown and mouseup events invoked on different DOM elements underneath where you touched.  This happens even if you only touched the screen once. I was able to intercept mouse events and prevent their default actions to mitigate this behavior.

Sounds confusing, right?  Well, it can certainly be tricky.  Luckily for us all, I was able to encapsulate all of this functionality inside of a reusable JavaScript class that anyone can use without needing to understand all of the ins & outs.   The TouchClick.js class is available in the example on github under “WinPhone-NoGrayBox“.  In the TouchClick.js library, it override the default HTMLElement’s addEventListener function and intercepts all calls to addEventListener( “click”… ) and replaces it with the TouchClick behavior, which will perform a click action, but without the gray highlight box.  Thus making your app experience better, and keeping your code simple.

Once you include TouchClick.js, you add event listeners as you normally would, and it even works with jQuery’s event wrappers:

myElement.addEventListener( "click", clickHandler1 );
$("#myElement2").on( "click", clickHandler2 );
$("#myElement3").click( clickHandler3 );

Download TouchClick.js today from today, and start building more great experience for Windows Phone using PhoneGap.

Thanks to @purplecabbage for pointing me in the right direction with mouse events inside of PhoneGap on Windows Phone!

More detail will be available on the app shown in the video at a later date – That app was created using app-UI for rich mobile experiences.

15 replies on “Getting rid of the “Gray Box” in PhoneGap for Windows Phone”