starter

Get Started: Your First Interactive Ink Application

In this practical, you'll learn how to create and run our first Interactive Ink (abbr. as IInk in the following context) application from the scaffold:

• Get Started: Your First Interactive Ink Application
  • App Preview
  • IInk Engine
  • Your First Editor View
  • Interactivity
  • Summary

[!ATTENTION] In this practical, it is assumed that you have basic fundamentals of Android development (Kotlin).

App Preview

This simple application displays a page with guidelines, where you can write with your active pen or finger, and get the recognized result showing above your handwriting ink.

Here is what the final app will look like:

IInk Engine

An IInk application works with an Engine object, the runtime of MyScript IInk SDK.

[!ATTENTION] Please make sure you manage to run your app with a valid certificate. If not, please follow the instructions of IInk Certificate section.

The scaffold has instantiated an IInk engine for you in InteractiveInkApplication.

Let the engine create a ContentPackage:

// create a content package package.
val packageFile = File("my_iink_package.iink")
try {
  contentPackage = createPackage(packageFile)?.let {
    // create a content part.
    contentPart = it.createPart("Text Document")
  }
} catch (e: Exception) {
  Log.e(TAG, "Failed to open package [$packageFile].", e)
}

As you can see in code, besides the configurations of Engine, a ContentPackage and a ContentPart are also created. In fact, IInk SDK works with a strutural storage, as stated in the official docs:

ContentPackage: A package is a container storing ink and its interpretation as an ordered collection of parts. It can be saved as a file on the file system and later reloaded or shared between users.

ContentPart: A part corresponds to a standalone content unit that can be processed by iink SDK.

[!TIPS] You can change the part type on the creation of the ContentPart to try different recognitions, as is suggested in the code comments.

More details about supported content part types refers to MyScript Developer.

Your First Editor View

The user interface (UI) of an IInk application consists of one or multiple EditorViews implemented in :myscript-iink module. This is the official implementation of MyScript IInk samples for Android, and you are encouraged by MyScript to use directly the UI implementations of IInk.

Include editor_view into the root layout:

<!-- activity_main.xml -->
<include layout="@layout/editor_view" />

Then initialize the EditorView in MainActivity:

/* MainActivity.kt */
private lateinit var editorView: EditorView

override fun onCreate(savedInstanceState: Bundle?) {
  // ...
  editorView = findViewById<EditorView>(R.id.editor_view).also { init(it) }
}

private fun init(view: EditorView) {
  // TODO: initialize the editor view.
}

[!INFO] Here we save the EditorView instance for later usage.

To initialize the EditorView, you'll have to:

1 - plug the Engine into the EditorView:

/* MainActivity.kt */
engine?.let { editorView.setEngine(it) }

2 - Initialize input mode:

/* MainActivity.kt */
editorView.inputMode = InputController.INPUT_MODE_AUTO

There are several input modes implemented in InputController in the module :myscript-iink:

• INPUT_MODE_FORCE_PEN: the InputController will behave as if all user input were pen input.
• INPUT_MODE_FORCE_TOUCH: the InputController will behave as if all user input were touch input.
• INPUT_MODE_AUTO: the InputController will automatically behave according to the pen or touch user pointer input.

Warning

InputController has also implemented another input mode INPUT_MODE_NONE, however, it actually results in the same behaviors as INPUT_MODE_AUTO.

[!INFO] If you have any further question about it, please go contact the MyScript IInk SDK team or fire an issue under the official repository.

If you have a better idea fixing this, please fork their repository and make a pull request to them.

3 - Attach the ContentPart to the Editor of the EditorView:

/* MainActivity.kt */
editorView.editor?.part = contentPart

4 - Visualize the EditorView:

/* MainActivity.kt */
editorView.visibility = View.VISIBLE

[!INFO] The EditorView is set invisible by default in the layout editor_view.xml.

Now build and run your app, then you'll be able to interact with MyScript IInk, like the preview at the beginning of this practical.

Interactivity

By default, MyScript IInk provides the following gestures for editing (images from the official docs):

Gesture	Preview
Erase
Break
Join
Highlight
Empasis

These gestures can satisfy most of editing needs. You can play with these gestures in the application you create in this practical.

[!ATTENTION] Not all editing gestures are compatible for all types of content. Please check compatibilities in official docs.

[!PS] To non-European friends: a × means compatible in the table, don't be confused.

Besides, there are 4 other editing:

Editing	Preview
Clear
Redo & Undo
Typeset (Double-tap)
Typeset (Programmatically)

editorView.editor?.let {
  // wait for the editor to be idle.
  if (!it.isIdle) it.waitForIdle()
  // convert all you handwritten content into typeset result.
  it.convert() // see [!ATTENTION] section below.
  // undo your modifications if any
  if (it.canUndo) it.undo()
  // redo your modifications if any
  if (it.canRedo) it.redo()
  // clear all your content
  it.clear()
}

[!ATTENTION] The API Editor.convert() is not an official API but an extension function created in this practical, this extension API will be used instead of the official API Editor.convert(ContentBlock, ConversionState) for tentative comprehension.

fun Editor.convert() =
  getSupportedTargetConversionStates(null).firstOrNull()?.let { convert(null, it) }

Summary

• All interactive ink applications are driven by an Engine, whose initialization requires a valid, active certificate.
• All interactive ink UI requires an EditorView with a basic implementations of interactive ink, each EditorView owns an Editor for manipulations of ink interactivity.
• The interactive ink Editor works with ContentPart, which is created by a ContentPackage created by Engine.
• MyScript Interactive Ink SDK has default interactive gestures integrated: erase, break (words / lines), join (words / lines), highlight and emphasis (underline / double-underline), besides, the conversion is also interactive by double-tap on the handwritten ink, as long as the touch is activated for ink interactivity.
• There are also 2 editing stacks integrated in MyScript Interactive Ink SDK: undo and redo, which can be implemented via the corresponding APIs of Editor.