Warning Unreleased Docs! - You may be viewing documentation that reflects an upcoming release and the functionality described may not be in the current version you are using. Change the version above to the most recent version.

SignalIndicators

Methods4
Methods - Class
hideIconshowIconstopWlanStatuswlanStatus
Properties1
Class Properties
refreshInterval
Examples2
Retrieve the WLAN statusWorking with the Signal indicator
Remarks3
Icon LayoutOverlapping IndicatorsScreen Orientation

The Signal API is used to notify the user of the strength of the WLAN signal. For Windows Mobile / CE, only Symbol 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"

Note: 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.

(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.

(All platforms support wlanStatus which can be used to draw your own level indicator or display an appropriate graphic.)

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 push the icon 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 "::" for all "." when referencing constants)
      String:left

      See the remarks section for illustrations of icon layout

      Constant: Rho::SignalIndicators.SIGNAL_LAYOUT_RIGHT (For Ruby use "::" for all "." when referencing constants)
      String:right

      See the remarks section for illustrations of icon layout

      Constant: Rho::SignalIndicators.SIGNAL_LAYOUT_UP (For Ruby use "::" for all "." when referencing constants)
      String:up

      See the remarks section for illustrations of icon layout

      Constant: Rho::SignalIndicators.SIGNAL_LAYOUT_DOWN (For Ruby use "::" for all "." when referencing constants)
      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.

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.

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, CE, 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, CE, Android
    • dhcpStatic : STRING

      Whether the unit has 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, CE, 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, CE, 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, CE, Android
    • dhcpStatic : STRING

      Whether the unit has 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, CE, 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

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.

Default: 5000

Property Access:

  • Instance: This property can be accessed via an instance object of this class:
    • myObject.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

  function signal_status_sync(){

    signalValue = Rho.SignalIndicators.wlanStatus;
    console.log(signalValue);
    console.log("Signal Strength is: " + signalValue['signalStrength']);
  }
                    
                            
  def signal_status_sync
    signalValue = Rho::SignalIndicators.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

  function signal_status_async(){
    console.log("Registering Signal Callback");
    Rho.SignalIndicators.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::SignalIndicators.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

  function show_signal_icon(){
    Rho.SignalIndicators.showIcon({});
  }
                    
                            
  def show_signal_icon
    Rho::SignalIndicators.showIcon({})
  end

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

  function show_signal_icon(){
    Rho.SignalIndicators.showIcon({color:'#0000FF',layout: Rho.SignalIndicators.SIGNAL_LAYOUT_UP});
  }
  
                            
  def show_signal_icon
    Rho::SignalIndicators.showIcon({color:'#0000FF',layout: Rho::SignalIndicators.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.