A first example

Let's look at a minimal example to get to know the framework and see how to run and test your "mini-apps".

Here is the source code for the first example (basic.kt):

//
// Tiny mini-app for the CS109 Android framework
//

import org.otfried.cs109.Color
import org.otfried.cs109.TextAlign
import org.otfried.cs109.Context
import org.otfried.cs109.MiniApp
import org.otfried.cs109.Canvas

class Main(val ctx: Context) : MiniApp {
  init {
    ctx.setTitle("Demo #1")
  }

  override fun onDraw(canvas: Canvas) {
    canvas.clear(Color(255, 255, 192))
    canvas.setColor(Color.BLUE)
    canvas.setFont(48.0)
    canvas.drawText("CS109", canvas.width / 2.0, 200.0, TextAlign.CENTER)
    canvas.drawCircle(canvas.width / 2.0, 400.0, 60.0)
  }
}

As you see, a mini-app must define a class whose name is Main, that implements the MiniApp framework, and that has a constructor taking an org.otfried.cs109.Context argument.

The class Main must define a method called onDraw(canvas). Since the method is required by the framework, we must use the override keyword, just like when you define toString for a class.

This method is responsible for drawing the appearance of the mini-app, using the methods of the provided canvas object. This canvas provides exactly the same methods as we met before in the drawing section.

We compile the mini-app as follows:

$ ktc-dex basic.kt

The result of the compilation are two files, basic.jar and basic.dex. These are packages that contain all the classes that are part of the mini-app.

We will first test the mini-app on a simple emulator that runs on your PC and that allows you to test mini-apps more easily:

$ kt-emulator basic.jar

A window like the following should appear:

Since our mini-app works on the emulator, it's time to test it on an Android phone. You will need a phone running Android 4.2 or higher, and you need to install the KAIST CS109 App.

Copy the file basic.dex to your phone, and start the app. As long as no mini-app is loaded, it will greet you with a screen like this:

Use the menu button to open the menu and select "Load new mini-app". You can now use your file manager to select the basic.dex file that you just placed on your phone. (If your phone only offers you to open the photo gallery and your music collection, but not look at files in general, then you have no file manager installed.)

If all goes well, your mini-app should now be running on your phone:

Security advice: The mini-app loaded from the DEX-file is running directly on your phone, and it has potentially access to all the functions of your phone. Do not use the KAIST CS109 app to load DEX-files that you found on the internet, or that were sent to you. As a precaution, the KAIST CS109 does not have permission to write to the phone's storage or to send data over the internet, so that even if you accidentally execute some malicious code, nothing serious should happen.