Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

SignalIndicators

The Signal API is used to notify the user of the strength of the WLAN signal. For Windows Mobile / CE, only Zebra Technologies' devices are supported and it is also possible to display a small indicator showing the available signal. The WLAN signal strength is not available on Windows Phone 8 and therefore this API is not supported on that platform.

Enabling the API

In order to use this API you must include the following extension in your build.yml.

extensions: ["indicators"]

The indicators extension is also included automatically if you specify the following in your build.yml.

app_type: "rhoelements"

If you are building a Windows Mobile or Windows CE app with this API, you must set your app_type as “rhoelements” in your build.yml as shown here.

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

Methods

hideIcon()

Hide the icon if it has been previously set by the ‘showIcon’ call.

Javascript Ruby Android Windows Mobile, Windows CE, Windows Embedded Zebra Devices Only (All platforms support wlanStatus which can be used to draw your own level indicator or display an appropriate graphic.)

Synchronous Return:

Void

Method Access:

Class Method: This method can only be accessed via the API class object.
- Javascript: Rho.SignalIndicators.hideIcon()
- Ruby: Rho::SignalIndicators.hideIcon()

showIcon(HASH propertyMap)

Overlays a small signal icon on top of the view indicating the remaining signal strength. This is particularly useful in full screen applications which cover the system signal level indicator.

Parameters

propertyMap : HASH

The properties associated with the indicator, its position and colour.

left : INTEGER Default: [Top right of the screen]

The absolute horizontal position of the indicator in pixels. This value is relative to the screen and not the view, so non-fullscreen applications should take care not to display the indicator off screen.
top : INTEGER Default: [Top right of the screen]

The absolute vertical position of the indicator in pixels. Positive numbers go towards the bottom of the screen. The value is relative to the screen and not the view, so non-fullscreen applications should take care not to display the indicator off screen.
layout : STRING Default: [Right]

Sets the orientation of the icon, see the remarks section for illustrations.

Possible Values :

Constant: Rho::SignalIndicators.SIGNAL_LAYOUT_LEFT (For Ruby use "::" instead of ".")
String:left

See the remarks section for illustrations of icon layout

Constant: Rho::SignalIndicators.SIGNAL_LAYOUT_RIGHT (For Ruby use "::" instead of ".")
String:right

See the remarks section for illustrations of icon layout

Constant: Rho::SignalIndicators.SIGNAL_LAYOUT_UP (For Ruby use "::" instead of ".")
String:up

See the remarks section for illustrations of icon layout

Constant: Rho::SignalIndicators.SIGNAL_LAYOUT_DOWN (For Ruby use "::" instead of ".")
String:down

See the remarks section for illustrations of icon layout
color : STRING Default: #000000

The color of the icon. This value must be specified as a Hex value in the format #000000 to #FFFFFF. Alpha values are not supported, i.e. you can only use the component parts RRGGBB.

Synchronous Return:

Void

Method Access:

Class Method: This method can only be accessed via the API class object.
- Javascript: Rho.SignalIndicators.showIcon(HASH propertyMap)
- Ruby: Rho::SignalIndicators.showIcon(HASH propertyMap)

stopWlanStatus()

If the signal is being retrieved via callback, by a previously invoked call to wlanStatus, this method will stop the callback from firing.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Synchronous Return:

Void

Method Access:

Class Method: This method can only be accessed via the API class object.
- Javascript: Rho.SignalIndicators.stopWlanStatus()
- Ruby: Rho::SignalIndicators.stopWlanStatus()

wlanStatus(CallBackHandler callback)

Retrieve the current signal status. If a callback is provided to retrieve the signal then it will be called periodically at the specified refreshInterval. On Android, instead of being called periodically, the callback will be called when one of the below values changes.

Javascript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

signalStrength : INTEGER

The signal strength as a value between 0 and 100. Not supported on iOS
Platforms:WM, Android
essid : STRING

The current ESSID
macAddress : STRING

The Device’s MAC address
adapterName : STRING

The Device’s adapter name
dhcpServer : STRING

The current DHCP server’s address. Always populated on Android, even on static IP configurations. Not supported on iOS
Platforms:WM, Android
dhcpStatic : STRING

Whether the unit hsa a static or DHCP address. Not available on Android and iOS.
Platforms:WM
gateway : STRING

The current gateway IP address
ipAddress : STRING

The device’s IP address
rssi : STRING

Signal strength in RSSI terms. Not supported on iOS.
Platforms:WM, Android
subnetMask : STRING

The current subnet mask
wins : STRING

The current WINs server IP address. Not available on Android and iOS.
Platforms:WM

Synchronous Return:

HASH : this method also supports async callbacks - check the Callback tab for callback return parameters.
- signalStrength : INTEGER
  
  The signal strength as a value between 0 and 100. Not supported on iOS
  Platforms:WM, Android
- essid : STRING
  
  The current ESSID
- macAddress : STRING
  
  The Device’s MAC address
- adapterName : STRING
  
  The Device’s adapter name
- dhcpServer : STRING
  
  The current DHCP server’s address. Always populated on Android, even on static IP configurations. Not supported on iOS
  Platforms:WM, Android
- dhcpStatic : STRING
  
  Whether the unit hsa a static or DHCP address. Not available on Android and iOS.
  Platforms:WM
- gateway : STRING
  
  The current gateway IP address
- ipAddress : STRING
  
  The device’s IP address
- rssi : STRING
  
  Signal strength in RSSI terms. Not supported on iOS.
  Platforms:WM, Android
- subnetMask : STRING
  
  The current subnet mask
- wins : STRING
  
  The current WINs server IP address. Not available on Android and iOS.
  Platforms:WM

Method Access:

Class Method: This method can only be accessed via the API class object.
- Javascript: Rho.SignalIndicators.wlanStatus(CallBackHandler callback)
- Ruby: Rho::SignalIndicators.wlanStatus(CallBackHandler callback)

Properties

refreshInterval : INTEGER 1.0.0

A callback to retrieve the signal strength can be specified to occur periodically with the wlanStatus method. This value specifies the periodicity of the callback as well as the update frequency of the indicator icon, if shown. On Android this value is not used as the signal icon will be updated as soon as the signal strength changes.

Javascript Ruby iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Default: 5000

Property Access:

Class: This property can only be accessed via the API class object.
- Javascript: Rho.SignalIndicators.refreshInterval
- Ruby: Rho::SignalIndicators.refreshInterval

Examples

Retrieve the WLAN status

Synchronously: If you are only interested in the current signal state, for example to decide whether to perform some online operation then you can immediately determine the WLAN status as follows

Javascript
Ruby

  function signal_status_sync(){

    signalValue = Rho.Signal.wlanStatus;
    console.log(signalValue);
    console.log("Signal Strength is: " + signalValue['signalStrength']);
  }

  def signal_status_sync
    signalValue = Rho::Signal.wlanStatus
    puts signalValue
    puts "Signal Strength is: " + signalValue['signalStrength']
  end

Asynchronously: If you want to be notified of changes to the WLAN signal then you can register to receive values through a callback

Javascript
Ruby

  function signal_status_async(){
    console.log("Registering Signal Callback");
    Rho.Signal.wlanStatus(signalEvent);
  }

  function signalEvent(params){
    console.log("Signal Event: (Asynchronous).  Strength: " + params["signalStrength"] + ", ESS ID: " + params["essid"] + ", MacAddress: " + params["macAddress"] + ", AdapterName: " + params["adapterName"] + ", DHCP Server: " + params["dhcpServer"] + ", DHCP Static: " + params["dhcpStatic"] + ", Gateway: " + params["gateway"] + ", IP Address: " + params["ipAddress"] + ", RSSI: " + params["rssi"] + ", Subnet Mask: " + params["subnetMask"] + ", Wins: " + params["wins"]);
  }

  def signal_status_async
    puts "Registering Signal Callback"
    Rho::Signal.wlanStatus(url_for(:action => :signalEvent))
  end

   def signalEvent
    puts "Signal Event: (Asynchronous).  Strength: #{@params["signalStrength"]}, ESS ID: #{@params["essid"]}, MacAddress: #{@params["macAddress"]}, AdapterName: #{@params["adapterName"]}, DHCP Server: #{@params["dhcpServer"]}, DHCP Static: #{@params["dhcpStatic"]}, Gateway: #{@params["gateway"]}, IP Address: #{@params["ipAddress"]}, RSSI: #{@params["rssi"]}, Subnet Mask: #{@params["subnetMask"]}, Wins: #{@params["wins"]}"
  end

Working with the Signal indicator

If you just want to display the signal indicator in the default position and default colour then call as follows

Javascript
Ruby

  function show_signal_icon(){
    Rho.Signal.showIcon({});
  }

  def show_signal_icon
    Rho::Signal.showIcon({})
  end

To display the signal icon at the default position but blue and vertical specify as follows

Javascript
Ruby

  function show_signal_icon(){
    Rho.Signal.showIcon({color:'#0000FF',layout: Rho.Signal.SIGNAL_LAYOUT_UP});
  }

  def show_signal_icon
    Rho::Signal.showIcon({color:'#0000FF',layout: Rho::Signal.SIGNAL_LAYOUT_UP})
  end

Remarks

Icon Layout

Windows Mobile / CE and Handheld devices support the display of a small signal icon, this section explains the layout parameter which can be provided to showIcon(…).

Layout:Left

Left Layout Signal Indicator

Layout:Right

Right Layout Signal Indicator

Layout:Up

Up Layout Signal Indicator

Layout:Down

Down Layout Signal Indicator

Overlapping Indicators

The position of the signal and battery indicators should not be set to overlap

Screen Orientation

The indicator positions are absolute and so when rotating the screen you should also move the indicator positions accordingly to accommodate the new screen layout.