CETerm Web Browser support for Windows Mobile 6.5.3

Version 1

    Verified Product Versions

    Wavelink Naurtech CETerm 5.7

    CETerm Web Browser support for Windows Mobile 6.5.3

     

    Introduction

    CETerm V5.7.1 now provides the ability to select either the legacy "Pocket Internet Explorer" (PIE) browser component or the newer "Internet Explorer Mobile 6" (IEM6) component used within IE.

    This enhancement puts the Windows Mobile browser on an equal footing with the browser in Windows CE. On Windows CE, the "Internet Explorer 6 for CE" (IE6CE) browser has always offered a more complete feature set, but the PIE browser did have better optimization of page layout on a small screen.

    The PIE browser has always been available in Windows Mobile and was used by IE on the device up until Windows Mobile 6.1.4. PIE is a "small footprint" browser intended for mobile devices and, as such, was missing some DOM features such as "onkeydown" events. CETerm features, such as "OnKey" <META> tags can be used to overcome the limitations and PIE is still a viable browser for industrial applications. In particular, if your application was written for PocketPC 2003 or Windows Mobile 5, there is no reason to switch to the IEM6 browser if PIE provides the behavior you need on a Windows Mobile 6.5.3 device.

    New web applications developed for Windows Mobile 6.5.3 devices should probably use the IEM6 browser because the behavior is closer to the browser expected on future Windows Embedded platforms.

    Using "Internet Explorer Mobile 6" (IEM6) in CETerm

    Using the new IEM6 browser presents a couple of challenges but they can be overcome. The two main challenges are controlling the layout of the rendered page, and the scrolling or panning of the page.

    IEM6 Layout

    The size and layout of the rendered page may not be similar to the layout under PIE or IE6CE. For IEM6, you may need to add some header elements to the HTML or change style sheets (CSS) to get the desired layout. We offer some tips below.

    IEM6 Scrolling

    As seen in IE on WM 6.5.3, the new IEM6 does not display "page-level" scrollbars. The user can "pan" the page by dragging the stylus on the screen. The same behavior is available under CETermor the screen can be shifted by actions tied to hardware keys. It is possible to display scoll bars on elements within the page, and these are controlled fully by the HTML/CSS of the page.

    IEM6 Layout Tips

    IEM6 needs some hints to layout a page within the limited screen area. We have identified three techniques that help constrain the layout.

    1. Specify a DOCTYPE in the page

    This technique will usually direct the IEM6 layout to stay within the physical limits of the screen, or to create a page with only vertical scrolling. Any DOCTYPE with "Mobile" in the name works. Here are two possible DOCTYPE declarations:

     <!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.2//EN" "http://www.openmobilealliance.org/tech/DTD/xhtml-mobile12.dtd"> 

    or

     <!DOCTYPE html PUBLIC "-//WAPFORUM//DTD XHTML Mobile 1.0//EN" "http://www.wapforum.org/DTD/xhtml-mobile10.dtd"> 

    2. Specify a "viewport" <META> tag in the page.

    The "viewport" <META> tag is a non-standard hint to the browser about the limits of the viewing area or the design of the HTML. The recommended "viewport" tag is:

     <meta name="viewport" content="width=device-width, height=device-height, initial-scale=1.0"> 

    In our experience, the effects of width, height and initial-scale are unpredictable. Explicit values can be used and we have seen cases where small changes in width in the 320 range can cause radically different layouts. If you choose to experiment with these values, you may need to try many variations to identify the best for your needs.

    3. Specify a legacy "mobileoptimized" <META> tag in the page.

    An older <META> tag used with PIE still has some effect, but the above two techniques are preferred. If your page is specifically designed to fit in a specified width you may want to try:

     <meta name="mobileoptimized" content="240"> 

    or the value 0 for auto-width.

    Some of these tips were taken from the article "Developing Web Applications for Internet Explorer Mobile 6 on Windows Mobile 6.5" http://msdn.microsoft.com/en-us/library/dd938878.aspx

    You may find additional helpful information in that article, but not all are applicable to the IEM6 control when hosted in CETerm. For example, you will not see the "panning-range" indicator or "zoom" controls under CETerm.

    IEM6 Scrolling Tips

    Because IEM6 does not display page level scrollbars you must use other techniques for scrolling the desired page area into view. Of course the best approach is to use the techniques described above for layout constraints and design your pages so that they fit within the screen area and do not require scrolling.

    We use the term "scroll" here to changed the displayed region of a page, but it may also be called "panning". Historically, scrolling has referred to vertical changes and panning to horizontal changes. We use the terms interchangably to refer to the display change.

    For pages which are larger than the screen area, we can offer several techniques in CETerm to scroll the pages.

    1. Scroll with native IEM6 behavior

    As a native IEM6 behavior, the arrow keys will shift the display region, if the arrow keys are not otherwise remapped in CETerm or processed by the HTML (e.g., onkeydown handler). Note that the arrow keys *must* be used to navigate the JavaScript "Error Dialog" that IEM6 sometimes displays for runtime errors. See the warnings below.

    You can define an "onkeydown" handler to remove the default arrow-key scrolling. For example:

     <script type="text/javascript"> // IEM6 will pan the screen if the focus is not in an // input element. // You can prevent the panning yet still allow the keys // to perform cursor movement in text elements.  function ignorePanKeys(e) { e = e || window.event;  // Ignore arrow keys if not in INPUT var n = e.srcElement.nodeName.toUpperCase(); if (n !== "INPUT") { switch(e.keyCode) { case 0x25:  // Left case 0x26:  // Up case 0x27:  // Right case 0x28:  // Down // stop event bubbling e.cancelBubble = true; e.returnValue = false; e.keyCode = 0; return false; } }  return true; } </script> ... <body onkeydown="return ignorePanKeys(event);"...> ... 

    2. Panning with stylus drag

    To allow panning with the stylus drag action, you can define and include "onmousedown" and "onmousemove" handlers in your HTML. For example:

     <script type="text/javascript">  // Pan Variables var panStartX; var panStartY; var panStartLeft; var panStartTop; var panFactor=100; // Percentage.  Less than 100 slows down pan  // Start pan actions for onmousedown function startPan(e) { e = e || window.event; var de = document.documentElement; var db = document.body;  // Don't start if within INPUT element var n = e.srcElement.nodeName.toUpperCase(); if (n !== "INPUT") { panStartX = e.clientX; panStartY = e.clientY; // Depending on the page structure, sometimes // documentElement indicates the scroll position and // sometimes the body best indicates the scroll position. panStartLeft = Math.max( de.scrollLeft, db.scrollLeft); panStartTop = Math.max( de.scrollTop, db.scrollTop); // Prevent selection extension document.selection.empty(); } else { panStartX = 0; // No pan panStartY = 0; } }  // Perform pan actions for onmousemove function movePan(e) { if (panStartX || panStartY) { e = e || window.event; var newLeft = (panFactor*(panStartX - e.clientX))/100 + panStartLeft; var newTop = (panFactor*(panStartY - e.clientY))/100 + panStartTop; window.scrollTo( newLeft, newTop ); } } </script> ... <body onmousedown="startPan()" onmousemove="movePan()"...> ... 

    3. Inject panning handlers into a page.

    If the page HTML cannot be altered, CETerm can "inject" the handlers into the page. These handers are essentially the same as those shown above but are compressed for injection.

     // WARNING: This is a CETerm script which is loaded into // WARNING: a script slot of CETerm.  It is not used // WARNING: in a web page  // WARNING: Any existing mouse handlers in the page will // WARNING: be displaced by these handlers.  // Inject onmousedown and onmousemove handlers to // provide panning via a stylus drag. function injectPanHandlers(session) { var d,w; var s = "var pSX=0,pSY=0,pSL,pST,pF=100;" + "document.onmousedown=function(e){e=e||window.event;" + "var de=document.documentElement,db=document.body;" + "if(e.srcElement.nodeName.toUpperCase()!=='INPUT'){" + "pSX=e.clientX;pSY=e.clientY;" + "pSL=Math.max(de.scrollLeft,db.scrollLeft);" + "pST=Math.max(de.scrollTop,db.scrollTop);" + "document.selection.empty();}else{pSX=0;pSY=0;}};" + "document.onmousemove=function(e){var nL,nT;" + "if(pSX||pSY){e=e||window.event;" + "nL=(pF*(pSX-e.clientX))/100+pSL;" + "nT=(pF*(pSY-e.clientY))/100+pST;" + "window.scrollTo(nL,nT);}};";  try { d = CETerm.Session(session).Browser.Document; d.parentWindow.setTimeout( s, 10 ); } catch(eee){} }  // This function performs the injection whenever a page is // loaded.  If you already use an OnDocumentDone() handler // you can add the "injectPanHandlers(session)" call to // your existing handler. function OnDocumentDone(session) { injectPanHandlers(session); } 

    4. Scroll using CETerm key remapping

    The IEM6 page can also be scrolled through CETerm key remapping to these actions

     "HScroll Right One"     IDA_HSCROLL_PLUSONE "HScroll Left One"      IDA_HSCROLL_MINUSONE "HScroll Right Page"    IDA_HSCROLL_PLUSHALF "HScroll Left Page"     IDA_HSCROLL_MINUSHALF "VScroll Up One"        IDA_VSCROLL_PLUSONE "VScroll Down One"      IDA_VSCROLL_MINUSONE "VScroll Up Page"       IDA_VSCROLL_PLUSHALF "VScroll Down Page"     IDA_VSCROLL_MINUSHALF 

    5. Invoke CETerm scrolling actions with an IDA command.

    The scrolling actions above can also be invoked through CETerm scripting by invoking the IDA command:

     // WARNING: This is a CETerm script which is loaded into // WARNING: a script slot of CETerm.  It is not used // WARNING: in a web page  // Invoke IDA directly: CETerm.PostIDA( "IDA_HSCROLL_PLUSONE", 0 ); 

    6. Invoke scrolling actions in the page from CETerm Scripting

    Scrolling actions within the page can also be invoked from CETerm scripting:

     // WARNING: This is a CETerm script which is loaded into // WARNING: a script slot of CETerm.  It is not used // WARNING: in a web page  // Apply scroll action in page. // Actions: // "left", "right", "pageLeft", "pageRight" // "up", "down", "pageUp", "pageDown" function doBodyScroll( session, scrollAction ) { try{ CETerm.Session(session).Browser.Document.body.doScroll(scrollAction); } catch(eee){} } 

    7. Invoke scrolling within the page with standard DOM methods

    Scrolling can also be performed entirely within the page using such DOM methods as:

     document.parentWindow.scrollTo( x, y ); // or document.body.doScroll( scrollAction ); 

    WARNINGS:

    1. IEM6 can "freeze" CETerm

    We have observed that IEM6 will lockup the CETerm application if there is an error in the onload handler JavaScript. The error dialog is not displayed and the device responds by beeping with any stylus touch. The only way we have found to escape the lock is to kill the CETerm process with a remote management tool or warm reset the device.

    We recommend testing any new onload logic in a desktop browser to be sure all logic that is independent of CETerm is correct before testing within CETerm.

    2. JavaScript Runtime Error Dialog

    The JavaScript runtime error dialog appears unusually "compressed" when displayed in CETerm. You can use the right-arrow key to move the contents and click on the "Show Details" button. This will expand the dialog slightly and the arrow keys can again be used to see the details of the run-time JavaScript error.