Overview

Single Character Widget is an interactive input method enabling users to handwrite text quickly, efficiently and without necessarily looking at the writing area. It is also particularly adapted to small devices, such as digital watches, smartphones, GPS navigation units, etc.

Single Character Widget is designed to ensure a natural, handwriting-based HMI with real-time recognition and ink editing gestures as well as word completion features. It is fast and responsive, even with large amount of text.

Single Character Widget can operate in two modes: iso_text and si_text, depending on the set resources:

  • ak-iso resources for isolated input (iso_text), i.e. character by character.

  • ak-superimposed resources for superimposed input (si_text).

Use cases

The below use cases are only examples of applications where Single Character Widget has been used, sometimes with additional features. Note that all available features are listed in the API.

SMS

Here is an integration example of Single Character Widget in an input method. In this scenario, the user handwrites a text message in a smartphone, with each character written over the previous one.

GPS

Here is an integration example of Single Character Widget in a GPS application. In this scenario, the driver handwrites superimposed characters on a device, and does not necessarily need to pay attention to the writing area.

Crosswords

Here is an integration example of Single Character Widget in a crossword application. In this scenario, the user handwrites isolated characters in the most natural way.

Math

Here is an integration example of Single Character Widget in a digital calculator. In this scenario, the user handwrites characters on top of each other, to display operations and final result.

Features

Character per character input
Canvas where text is entered, character by character, one on top of the other.

Real-time single characters
Real-time recognition of words where characters are written one after the other, with a time-out between characters. See the list of supported languages on the Developer Portal.

Real-time superimposed characters
Real-time recognition of words where characters are written on top of each other without any time-out between characters. See the list of supported languages on the Developer Portal.

Editing gestures
Single tap, long press, return, space and backspace gestures. See below our recommendations.

Word completion
Completion options on partially recognized words.

Word prediction
Prediction options on recognized words.

Option list (candidates)
Character and word option list that potentially match the input ink.

Customization options
Ink color, ink thickness, ink fade-out delay, ink effect, background.

Languages

Single Character Widget supports:

Recommendations

Gesture detection

Single Character Widget supports the following gestures: single tap, long press, return, backspace, space.

Except for space gesture, gestures can be associated with any action. See below a list of suggested actions for each of these.

The space gesture cannot be configured and any line drawn from left to right will be interpreted as a space. Note that you can also create a space button in the UI.
User action  Gesture Description  Sample & default actions
Single tap Briefly touch the screen n/a
Long press Tap and hold down n/a
Return Draw a line downwards then leftwards Insert a hard line break
Backspace Draw a line leftwards Delete a letter
Space Draw a line rightwards Insert a space
These gestures might be confusing for your users at first, so you might want to integrate only some of these. If you choose to integrate all the gestures, we recommend you clearly explain these to your users to avoid any confusion.

Chinese and Japanese

For Chinese and Japanese, we recommend:

  • deactivating space and backspace gestures - to avoid confusion with some characters,
  • increasing the ink fade-out delay - so that strokes are displayed longer, thus allowing to see the whole characters,
  • activating auto spacing.
Auto spacing only works in Chinese and Japanese.

Integration

General information about ATK (licenses, samples, etc.) is available in the ATK Overview section.
Please make sure to use the latest version of Android Studio and have all Android tools and SDK (level 15 or up) installed and configured properly.

Step 1 - Download your Certificate

  1. Log in at https://atk.myscript.com.
  2. In the Applications tab, click Create application.
  3. Enter your application name and its description, then click Create.
  4. Click Open, then Create certificate.
  5. Enter the package name that can be found in AndroidManifest.xml and select the target environment, then click Create.
  6. Click on the .java download icon to download the corresponding certificate.
  7. Paste it in your project and start creating your app.
You need one certificate per application and per platform. You can integrate several widgets in one application.

Step 2 - Configure your Dependencies

  • In the build.gradle file of your project, add:
repositories {
    flatDir {
        // Location of your package's `libs` directory containing `*.aar` files.
        dirs 'path/to/libs'
    }
}
  • In the dependencies section, add:
compile 'com.android.support:appcompat-v7:23.+'

compile(name: 'MyScript_ATK-Core-android-component', ext: 'aar')
compile(name: 'MyScript_ATK-Text-android-component', ext: 'aar')
compile(name: 'MyScript_ATK-IMCommon-android-component', ext: 'aar')
compile(name: 'MyScript_ATK-SingleCharWidget-android-widget', ext: 'aar')

Step 3 - Add Resources

Copy the assets directory from samples/SingleCharWidgetSample/src/main into your project. Resources should include at least an ak resource. More lk resources can be added as well, to improve and/or constrain the handwriting recognition.

Example: To use US English in superimposed, resources should be at least:

  • resources/latin/latin-ak-superimposed.lite.res,
  • resources/en_US/en_US-lk-text.lite.res,
  • resources/mul/mul-lk-gesture.res,
  • conf/en_US.conf.
Resources are available for download on the Developer Portal. You can also customize your own resources: Check the Developer Tools page to discover how.

Step 4 - Add a Layout Resource

To integrate the Single Character Widget view, add the following snippet in your layout.

<com.myscript.atk.scw.SingleCharWidget
    android:id="@+id/singleChar_widget"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
/>

Step 5 - Start with Minimal Integration Code

An Internet connection is required to launch and run ATK applications. To authorize it, add the following line in the AndroidManifest.xml file:

<uses-permission android:name="android.permission.INTERNET" />
However, a 30-day grace period is offered, from the moment you first launch your application. A connection will then be mandatory.

Edit the MainActivity class:

public class MainActivity extends AppCompatActivity implements
    SingleCharWidgetApi.OnConfiguredListener,
    SingleCharWidgetApi.OnTextChangedListener
{

  private static final String TAG = "SingleCharDemo";

  private SingleCharWidgetApi widget;

  @Override
  protected void onCreate(Bundle savedInstanceState)
  {
    super.onCreate(savedInstanceState);

    setContentView(R.layout.activity_main);

    widget = (SingleCharWidget) findViewById(R.id.singleChar_widget);
    if (!widget.registerCertificate(MyCertificate.getBytes()))
    {
      AlertDialog.Builder dlgAlert  = new AlertDialog.Builder(this);
      dlgAlert.setMessage("Please use a valid certificate.");
      dlgAlert.setTitle("Invalid certificate");
      dlgAlert.setCancelable(false);
      dlgAlert.setPositiveButton("OK", new DialogInterface.OnClickListener()
      {
        public void onClick(DialogInterface dialog, int which)
        {
          //dismiss the dialog
        }
      });
      dlgAlert.create().show();
      return;
    }

    widget.setOnConfiguredListener(this);
    widget.setOnTextChangedListener(this);

    // references assets directly from the APK to avoid extraction in application
    // file system
    widget.addSearchDir("zip://" + getPackageCodePath() + "!/assets/conf");

    // The configuration is an asynchronous operation. Callbacks are provided to
    // monitor the beginning and end of the configuration process and update the UI
    // of the input method accordingly.
    //
    // "en_US" references the en_US bundle name in conf/en_US.conf file in your assets.
    // "si_text" references the configuration name in en_US.conf
    widget.configure("en_US", "si_text");
  }

  @Override
  protected void onDestroy()
  {
    widget.setOnTextChangedListener(null);
    widget.setOnConfiguredListener(null);

    super.onDestroy();
  }

  @Override
  public void onConfigured(SingleCharWidgetApi widget, boolean success)
  {
    if(!success)
    {
      Toast.makeText(getApplicationContext(), widget.getErrorString(), Toast.LENGTH_LONG).show();
      Log.e(TAG, "Unable to configure the Single Char Widget: " + widget.getErrorString());
      return;
    }
    Toast.makeText(getApplicationContext(), "Single Char Widget Configured", Toast.LENGTH_SHORT).show();
    if(BuildConfig.DEBUG)
      Log.d(TAG, "Single Char Widget configured!");
  }

  @Override
  public void onTextChanged(SingleCharWidgetApi widget, String s, boolean intermediate)
  {
    Toast.makeText(getApplicationContext(), "Recognition update", Toast.LENGTH_SHORT).show();
    if(BuildConfig.DEBUG)
    {
      Log.d(TAG, "Single Char Widget recognition: " + widget.getText());
    }
  }
}

API

See the API documentation for Android.