com.smartgwt.client.docs

## Interface MobileDevelopment

-     public interface MobileDevelopment

  ### Mobile Application Development

  Smart GWT supports building web applications that can be accessed by mobile devices that support modern web browsers, specifically:
  - Safari on iOS devices (iPad, iPhone, iPod Touch)
  - Android's default (WebKit-based) browser
  - Windows Phone 7 (future, for 'Mango' and up)
  - Blackberry devices that use a WebKit-based browser (future)

  ### Finger / touch events

  Mobile and touch devices support "touch events" that correspond to finger actions on the screen. By default, Smart GWT simply sends touch events to UI components as normal mouse events. Specifically:

  - a finger tap gesture will trigger mouseDown, mouseUp and click events
  - a touch-and-slide interaction will trigger drag and drop, firing the normal Smart GWT sequence of dragStart, dragMove, and dragStop
  - a touch-and-hold interaction will trigger a contextMenu event, and will trigger a hover if no contextMenu is shown
  This means that most applications that are written initially to target desktop computers need little or no modification in order be able to run on tablet-sized devices (eg the iPad). For handset-sized devices (phones, iPod touch), conditional logic may need to be added to make different use of the screen real estate.

  ### Adapting to tablets and handsets

  Smart GWT provides the `isTablet` variable which can be used to determine whether a device is tablet-size (e.g. iPad, Nexus 7) or handset-size (phones, iPod touch, and similar smaller form-factor devices). In most cases Smart GWT will correctly determine whether the device running your application is a tablet. For any uncommon device for which this variable is incorrect, you can override Smart GWT's detection logic by defining the `isc_isTablet` global with the correct value before Smart GWT is loaded. Whenever the `isc_isTablet` global is defined, Smart GWT will use this value for Browser.isTablet instead of its own detection logic.

  ### Mobile look and feel

  We recommend using either the Enterprise, EnterpriseBlue or Graphite skins for applications that support mobile (or a custom skin based on one of these skins). These skins make maximum use of CSS3 to minimize the number of images that need to be loaded and the number of DOM elements used to create components.

  We also do not recommend attempting to mimic the native UI of each particular mobile platform, because:

  - if users access the same application via desktop and mobile browsers, consistent appearance between the desktop and mobile rendering of the application is more important for familiarity than looking similar to other applications on the mobile device
  - there is no single consistent appearance across Android devices because different manufacturers customize the platform a great deal, so there's no single appearance to mimic
  - mobile platform design overhauls, such as the major changes from iOS6 to iOS7, can easily invalidate efforts to look like native applications on the device

  ### Adapting to Screen Size and Orientation Change

  Safari on the Apple iPod/iPhone supports explicitly configuring the viewport as detailed here: http://developer.apple.com/safari/library/documentation/AppleApplications/Reference/SafariWebContent/UsingtheViewport/UsingtheViewport.html. Including these meta tags in your bootstrap HTML file will allow you to set a default "zoom level" - how many pixels show up on the screen in landscape or portrait mode as well as disabling the user's standard zoom interactions. We also have `an API` to configure the viewport programmatically at runtime.

  It is recommended to start with the following viewport meta tag in the bootstrap HTML file:
  `<meta name="viewport" content="initial-scale=1">`
  .. and then use `Page.updateViewport()` to update the viewport meta tag. On tablet devices (see `isTablet`), it is recommended to scale the viewport to 125% via:
  `Page.updateViewport(1.25, null, null, true);`
  On handsets, it is recommended to set the viewport width to 700 via:
  `Page.updateViewport(null, 700, null, true);`

  Note that the `Page.getOrientation()` API may be used to determine the current orientation of the application, and `the page orientationChange event` will fire whenever the user rotates the screen allowing applications to directly respond to the user pivoting their device.

  ### Packaging as a native application

  Via "packaging" technologies such as PhoneGap/Cordova and Titanium, a Smart GWT web application can be packaged as an installable native application that can be delivered via the "App Store" for the target mobile platform. Applications packaged in this way have access to phone-specific data and services such as contacts stored on the phone, or the ability to invoke the device's camera.

  Both Titanium and PhoneGap provide access to the underlying native device APIs such as the accelerometer, geolocation, and UI. Both frameworks enable application development using only JavaScript, CSS and HTML. Additionally they provide development environments that work across a wide variety of devices.

  PhoneGap has good support for native device APIs as noted here. Titanium has similar support. There are differences between the two environments and how they expose their APIs, though both provide Xcode-compatible projects that can be compiled and run from the Xcode IDE. See `Integration with Titanium` and `Integration with PhoneGap` for more information.

  See Also:
    `Page.getOrientation()`, `Page.updateViewport(java.lang.Float, java.lang.Integer, java.lang.Integer, java.lang.Boolean)`