Because we will be interacting with Android, the first order of business is to get oriented with the LuaJava bridge. I highly recommend reading this write-up which goes over the process of exporting to Android as well as the luajava API with an example application:
The best place to start when looking to perform any kind of feature on Android is to first figure out how it would be accomplished in a native Android setting. Today we’ll be looking at how to create a custom launcher using Storyboard.
First order of business is modifying your Android manifest file. You will have to export your Android manifest file from Storyboard. You can do this via:
Storyboard Application Export Configuration > Change Packaging Method to Native Android Application
Select the Manifest Tab > Manifest File (under Advanced Options) > Export current manifest settings to a file
Choose the location you wish to export your manifest file to and click Save.
Open this xml file in any text editor of your choice, you can even open it in Storyboard if you want.
The first thing we have to change is the content inside the activity tag. By default your manifest will contain:
<intent-filter>
<action android:name="android.intent.action.MAIN"/>
<category android:name="android.intent.category.LAUNCHER"/>
</intent-filter>
Simply replace <category android:name="android.intent.category.LAUNCHER"/> with these two lines:
<category android:name="android.intent.category.HOME"/> <category android:name="android.intent.category.DEFAULT"/>
What this does is ensures the Android OS identifies this application as a launcher. This means that it can be loaded when the system boots, and can be shown when the “home” button is pressed.
Additionally, it is a good idea to specify that this application is a “singleTask” activity.This means that there can only be one instance of the activity and it is always at the root of the activity stack.
To do this, add this line within your activity tag:
android:launchMode="singleTask"
And to finish up the modifications to your manifest, I would ensure that the manifest’s package name for your application matches the package name described in Storyboard. You can see and modify the package name in Storyboard within the Storyboard Application Export Configuration window.
Upon first exporting the default manifest, the package name does not match the Android Unique Application Identifier shown in the image above.
<manifest xmlns:android="http://schemas.android.com/apk/res/android" android:versionCode="1" android:versionName="1.0" package="android_launcher_demo">
So we just want to change it to reflect the unique identifier:
<manifest xmlns:android="http://schemas.android.com/apk/res/android" android:versionCode="1" android:versionName="1.0" package="com.storyboard.android_launcher_demo">
After all these changes you will have a manifest file that looks like:
<?xml version="1.0" encoding="utf-8" standalone="no"?><manifest xmlns:android="http://schemas.android.com/apk/res/android" android:versionCode="1" android:versionName="1.0" package="com.storyboard.android_launcher_demo">
<uses-sdk android:minSdkVersion="11"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<supports-screens android:xlargeScreens="false"/>
<application android:hasCode="true" android:icon="@drawable/icon" android:label="@string/app_name">
<activity android:launchMode="singleTask" android:configChanges="orientation|keyboardHidden" android:label="@string/app_name" android:name="com.crank.android.native_activity.StoryboardNativeActivity" android:screenOrientation="landscape">
<meta-data android:name="android.app.lib_name" android:value="sbandroid-activity"/>
<intent-filter>
<action android:name="android.intent.action.MAIN"/>
<category android:name="android.intent.category.HOME" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
</activity>
</application></manifest>
Now let’s take a look at actually launching an application.
Launching an application simply requires getting the launch intent for the specific application/package. This does mean you will need the package name/unique application identifier. In a native Java environment, launching chrome is as quick as:
Intent launchIntent = getPackageManager().getLaunchIntentForPackage("com.android.chrome");
startActivity(launchIntent);
All we have to do is convert that code into using the LuaJava module.
First step is to get an instance of the NativeActivity class. This is because Storyboard applications that are deployed to Android devices run as native activities. As a note, it is good practice to follow any LuaJava calls with nil checks.
local na = luajava.nativeActivity()
if (na == nil) then
print("no native activity")
return
end
Next step is to get an instance of the PackageManager class. The PackageManager class can get information related to the applications/packages installed on the device.
local package_manager = na:getPackageManager()
if (package_manager == nil) then
print("No Package Manager Class")
return
end
Using the package manager instance, we can now get the launch intent for any package/application as long as we know the package name. Let’s continue with launching Chrome.
local launch_intent = package_manager:getLaunchIntentForPackage(“com.android.chrome”)
if (launch_intent == nil) then
print("No Launch Intent")
return
end
Finally, all that is left to do is launch the application/activity.
na:startActivity(launch_intent)
That’s all the setup required to create a custom Android launcher application using Storyboard.In this example, we’ve launched a native Android application (Chrome), but you can also use this to launch other Storyboard applications. As long as they’ve been installed on your device and you know their package name, simply swap the “com.android.chrome” package name with your Storyboard package name. Again, ensure the Android Manifest package name matches the Android Unique Application Identifier in the Export Configuration.
When exporting, ensure that the apk is being exported using the Android Manifest file that we modified earlier. In the Storyboard Application Export Configuration dialog, uncheck “Use default manifest file” and browse to the custom manifest file.
Click Run and you will have successfully packaged your launcher application.
Move the apk file over to your Android device and install it. You will have to set your default Home application to be your application that you’ve just installed. This can be done by pressing the home button, which will open a dialog asking you to choose which Home launcher you wish to use.
It can also be set by navigating to Settings > Apps and Notifications > Default Apps > Home App
Click that and set it to your Storyboard application.
That’s it! Congratulations! Many cool interactive experiences can be made with this, so be sure to experiment.