From wiki.ginstr.com
Jump to: navigation, search
added in Milestone 100

gn:act_service

Description
Action is used to initialize a ginstr launcher service, to configure it's parameters or to stop the service.
Always only one instance of service and it's configuration exists.
In order to use the service, a listener has to be attached to it.
Action returns
void

Action signatures

[gn:act_service]|[serviceId;serviceParameters{n}]
Parameter Description
serviceId Name of the service which will be used
  • Valid services:
    • nfc, provides nfc features
    • gps, provides gps features
    • qr, provides qr features
serviceParameters{n} Parameters of service which are configured.
Parameters always have the id like "start", "stop", "triggerActionSet", and various amount of properties.
The service parameters are separated by ";" while internal properties are separated by ",".

Service parameters can also be "global" and "individual". Global service parameters are equal for all listeners which are attached to service and if the service configuration changes they are valid for all the attached listeners while "individual" service parameters are transferred to each listener on time of adding the listener. This enables ginstr app developer to have different configurations per listener i.e. we have 2 listeners we want that widget receives NFC id and we want that variable receives NFC embedded content.

  • nfc service parameters:
    • start (global) starts nfc service it needs to be called before any other service parameters
    • stop (global) stops nfc service and removes all service listeners, removes service configuration
    • nfcReadingsInterval,seconds (global) defines minimum time between two readings in seconds. If scan happens before minimum time dialog box will show to wait
    • triggerActionSet,targetId,actionSetId (individual) defines which action block should be executed after the scan is done, targetId is the widget which holds the action block and actionSetId is the name of the action set that will be executed. Behavior is similar to gn:act_trigger action
    • sourceType,type (individual) defines weather the scan should read the nfc id or nfc embedded content. Possible values for type are:
      • tagId
      • embedded
    • required (global) if set on service it will check if nfc hardware is ready for scanning. If hardware does not exists a popup message will be shown, if hardware is turned off android settings panel for nfc will be open and user can switch it on
    • alertType,type (global) defines if there will bi vibration or sound to alert the user during scan. Possible values for type are:
      • sound
      • vibrate
      • none
    • soundFile,fileNameWithExtension (global) defines if some other sound than default nfc scan sound will be played when alertType is set to sound. fileNameWithExtension needs to be replaced with actual file name and extension and the sound file must be located in assets folder of the ginstr app i.e. "glassPing.mp3"
    • emulatorsAllowed (global) bypasses hardware checks and allows usage of GnNfcEmulator widget

  • gps service parameters:
    • start (global) starts gps service it needs to be called before any other service parameters
    • stop (global) stops gps service and removes all service listeners, service parameter configuration is kept
    • mockLocation (global) if mocklocation is enabled it will randomly return one of 11 default mock locations
    • gpsPrecision (global) triggers higher precision readings only to be accepted as results. This might prolong receiving GPS lock.
    • triggerActionSet,targetId,actionSetId (individual) defines which action block should be executed after the scan is done, targetId is the widget which holds the action block and actionSetId is the name of the action set that will be executed. Behavior is similar to gn:act_trigger action
    • showAddress,value (individual) defines weather the address retrieved from nominatim server or coordinates will be set into target when GPS is obtained. Possible value for value is:
      • false configures gps service to show coordinates
    • providers (global) defines a list of active providers separated by comma, e.g. (gps,passive)
      • gps
      • network
      • passive
    • failover (global) defines a failover provider with additional parameters (e.g. failover,gps,5,30000)
      • provider - gps,network,passive
      • noOfRetires - hardcoded value, e.g. 5
      • timeout - hardcoded value in miliseconds e.g. 30000
    • disableMinDistanceCheck (global) disables minimum distance gps validation check

  • qr service parameters: (milestone 101)
    • start (global) starts qr service it needs to be called before any other service parameters, stop is always called after service is executed
    • autoEnableTorch (global) if autoEnableTorch is set as true it will start the service with device flash turned on. Possible value for value is:
      • true enables torch
    • triggerActionSet,targetId,actionSetId (individual) defines which action block should be executed after the scan is done, targetId is the widget which holds the action block and actionSetId is the name of the action set that will be executed. Behavior is similar to gn:act_trigger action

Example NFC service

Following nfc example has two nfc service configurations, in both services configuration it has 4 service parameters and to each configuration one service listener is attached. On load of the ginstr launcher screen start a nfc service which has maximum readings interval set to 1 second, alertType is set to vibrate so there will be vibration when scan is done, and when scan is done action set gn:act_set will be exectued on @+id/exampleFrame widget. Finally service listener will be attached with nfc service configuration that was just explained. When first scan is performed nfc service will be reconfigured and new listener will be added. This is just an example of how easy you can control flow with service configuration if required, in normal apps use cases might be much simpler.

hardware nfc data
04C357BA482780 - id
test - embedded
initial contents
@+id/screen_nfc_input widget
@variable/nfc_variable
variables.xml
<variable id="nfc_variable" type="text" defaultValue=""></variable>
screen.xml
<FrameLayout
    android:id="@+id/exampleFrame"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:visibility="gone"
    gn:act_beforeLoad="[gn:act_service]|[nfc;start;triggerActionSet,@+id/exampleFrame,gn:act_set;nfcReadingsInterval,1;alertType,vibrate],[gn:act_addServiceListener]|[nfc;@+id/screen_nfc_input]"
    gn:act_set="[gn:act_service]|[nfc;sourceType,embedded;alertType,sound;soundFile,glassPing.mp3;nfcReadingsInterval,10],[gn:act_addServiceListener]|[nfc;@variable/nfc_variable]" />

 <com.ginstr.widgets.GnEditText
    android:id="@+id/screen_nfc_input"
    android:layout_height="wrap_content"
    android:layout_width="match_parent"
    gn:dataType="text"
    gn:s_sourceType="input"/>
after 2 nfc scans contents
@+id/screen_nfc_input widget 04C357BA482780
@variable/nfc_variable test

Example GPS service

Following gps example has two gps providers (gps, passive) in combination with the failover provider. On load of the ginstr launcher screen start a gps service which has defined two providers (network,passive), one failover provider (gps) with additional parameters noOfRetires (5) and timeout (30000 ms) and disableMinDistanceCheck parameter which will disable minimum distance gps validator check. After the service is started, it will try to get coordinate from defined providers; in case there is no valid coordinate for more than 30 seconds or the service receives more than 5 invalid coordinates, the failover provider will be started and it will be active until one valid coordinate is returned. After that, the failover provider is stopped.

initial contents
@+id/Geofence
screen.xml
<RelativeLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    xmlns:gn="http://schemas.ginstr.com/ginstr"
    android:id="@+id/locationScreen"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    gn:act_beforeLoad="
        [gn:act_service]|[gps;start;providers,network,passive;failover,gps,5,30000;disableMinDistanceCheck],
        [gn:act_addServiceListener]|[gps;@+id/Geofence]">

<com.ginstr.widgets.GnEditText
    android:id="@+id/Geofence"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    gn:s_hint="@string/location_geofenceCenterPointHint"
    gn:style="@style/editableInputStyle"			
    gn:s_sourceType="input"/>
after gps service reading
@+id/Geofence 41.0,10.0