Build native widgets for Creative Mode.

Architecture

A widget is a native Android mini-app.

Each widget is compiled as its own Android package, has no launcher icon and runs with its own UID. CarBoxLauncher discovers its Activity through a public manifest contract and renders it inside a VirtualDisplay panel.

Requirements

Prepare Android Studio.

Use Android Studio with SDK Platform 34 and its bundled JDK 21. The current SDK supports boxes from Android 5.0 onward.

• Android Studio and Android SDK 34
• JDK 21 for Gradle, Java 17 source compatibility
• CarBoxLauncher with native widget support
• ADB connection for installation and logcat

Quick start

Start from the empty widget.

Open the Widget project from the CarBoxLauncher source tree and duplicate empty-widget. Give the copy a permanent application ID before writing your interface.

include ':my-widget'
project(':my-widget').projectDir = file('my-widget')

android {
  namespace 'com.example.mywidget'
  compileSdk 34

  defaultConfig {
    applicationId 'com.example.mywidget'
    minSdk 21
    targetSdk 34
    versionCode 1
    versionName '1.0.0'
  }
}

dependencies {
  implementation project(':carbox-widget-sdk')
}

Discovery contract

Declare one invisible widget Activity.

Never add the LAUNCHER category. Export only the CarBox widget action and declare API version plus initial panel dimensions.

<activity
  android:name=".MyWidgetActivity"
  android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout|density"
  android:excludeFromRecents="true"
  android:exported="true"
  android:resizeableActivity="true">

  <intent-filter>
    <action android:name="com.ferra.carboxlauncher.action.CARBOX_WIDGET" />
    <category android:name="com.ferra.carboxlauncher.category.CARBOX_WIDGET" />
    <category android:name="android.intent.category.DEFAULT" />
  </intent-filter>

  <meta-data
    android:name="com.ferra.carboxlauncher.widget.API_VERSION"
    android:value="1" />
  <meta-data
    android:name="com.ferra.carboxlauncher.widget.DEFAULT_WIDTH_DP"
    android:value="320" />
  <meta-data
    android:name="com.ferra.carboxlauncher.widget.DEFAULT_HEIGHT_DP"
    android:value="200" />
</activity>

Per-instance settings

Give each widget its own settings.

Add a SECOND exported Activity with the settings action. In edit mode CarBox shows a gear on the panel's bottom-left corner that opens it — external to the widget. CarBox passes a stable per-instance id: namespace your preferences with it so two copies of the same widget (e.g. one digital clock, one analog) keep independent settings. When the settings close, CarBox reloads that widget so it re-reads its config.

// Without windowIsTranslucent the widget window is opaque and the
// VirtualDisplay composites it over black → a "transparent" background
// shows BLACK instead of the launcher wallpaper. Required on Theme.CarBoxWidget:
<style name="Theme.CarBoxWidget" parent="android:style/Theme.Material.NoActionBar">
  <item name="android:windowIsTranslucent">true</item>
  <item name="android:windowBackground">@android:color/transparent</item>
</style>

<activity
  android:name=".SettingsActivity"
  android:exported="true"
  android:theme="@style/Theme.CarBoxWidgetSettings">
  <intent-filter>
    <action android:name="com.ferra.carboxlauncher.action.CARBOX_WIDGET_SETTINGS" />
    <category android:name="com.ferra.carboxlauncher.category.CARBOX_WIDGET" />
    <category android:name="android.intent.category.DEFAULT" />
  </intent-filter>
</activity>

<style name="Theme.CarBoxWidgetSettings" parent="android:style/Theme.Material.NoActionBar">
  <item name="android:windowIsTranslucent">true</item>
  <item name="android:windowBackground">@android:color/transparent</item>
  <item name="android:windowNoTitle">true</item>
  <item name="android:statusBarColor">@android:color/transparent</item>
  <item name="android:navigationBarColor">@android:color/transparent</item>
</style>

// per-instance config
String id = getIntent().getStringExtra(
    CarBoxWidget.EXTRA_WIDGET_INSTANCE_ID);
SharedPreferences prefs = getSharedPreferences(
    CarBoxWidget.configName(id), MODE_PRIVATE);
prefs.edit().putString("mode", "analog").apply();

// hide status + navigation bars
getWindow().getDecorView().setSystemUiVisibility(
    View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY
    | View.SYSTEM_UI_FLAG_FULLSCREEN
    | View.SYSTEM_UI_FLAG_HIDE_NAVIGATION
    | View.SYSTEM_UI_FLAG_LAYOUT_STABLE);

Runtime

Respect visibility and resize events.

Extend CarBoxWidgetActivity. Start timers, sensors and listeners only while visible, stop them when hidden, and adapt the UI whenever the panel size changes.

@Override
protected void onWidgetVisible() {
  handler.post(updateTask);
}

@Override
protected void onWidgetHidden() {
  handler.removeCallbacks(updateTask);
}

@Override
protected void onWidgetResize(int width, int height) {
  gauge.setCompact(width < 320);
}

Build

Compile and install on the box.

Run the Gradle task from the Widget root. Install the debug APK during development, then add it from Creative Mode.

$env:JAVA_HOME = 'C:\Program Files\Android\Android Studio\jbr'
.\gradlew.bat :my-widget:packageCarBoxWidget

adb -s BOX_IP:5555 install -r `
  my-widget\build\outputs\apk\debug\my-widget-debug.apk

Distribution

Inside a .cbwidget package.

The container is a ZIP with a compiled plugin.apk and manifest.json. The CarBox server validates production packages before they are offered for installation.

Before publishing

Release checklist

• Unique and permanent applicationId
• No LAUNCHER Activity
• Matching IDs and versions in Gradle and manifest.json
• Responsive layout at multiple panel sizes
• Timers and listeners stop when hidden
• No unnecessary Android permissions
• Tested installation, update and uninstall
• Icon, screenshots and offline behavior verified

Talk to the launcher

Use the CarBox Launcher API.

A widget runs inside a VirtualDisplay in its own process, so it cannot call the launcher directly — and calling startActivity() from a widget would open the app INSIDE the widget panel. The SDK exposes two channels: fire-and-forget commands (CarBoxWidgetCommands) and read-only state queries (CarBoxWidgetState). Import both from the Widget SDK.

// launch an app fullscreen (outside the panel)
CarBoxWidgetCommands.launchAppFullscreen(context, "com.spotify.music");
CarBoxWidgetCommands.launchFavorite(context, 1);   // favorite 1..5
CarBoxWidgetCommands.openAppDrawer(context);
CarBoxWidgetCommands.openAssistant(context);       // voice assistant
CarBoxWidgetCommands.speak(context, "Hello");
CarBoxWidgetCommands.openPhone(context);
CarBoxWidgetCommands.openContacts(context);
CarBoxWidgetCommands.call(context, "+391234567");  // or a contact name
CarBoxWidgetCommands.openNotifications(context);
CarBoxWidgetCommands.goToPage(context, 3);
CarBoxWidgetCommands.nextPage(context);
CarBoxWidgetCommands.previousPage(context);
CarBoxWidgetCommands.goHome(context);
CarBoxWidgetCommands.toggleEditMode(context);
CarBoxWidgetCommands.setEditMode(context, true);
CarBoxWidgetCommands.reloadPanels(context);
CarBoxWidgetCommands.setMode(context, "creative"); // or "dual"
CarBoxWidgetCommands.toggleMode(context);
CarBoxWidgetCommands.openSystemSettings(context, "wifi"); // wifi|bluetooth|data
CarBoxWidgetCommands.restartLauncher(context);

// follow the language selected in the launcher
String lang = CarBoxWidgetState.getLanguage(context); // "it" / "en"
applyLanguage(lang);

String mode = CarBoxWidgetState.getMode(context); // "creative" / "dual"
boolean creative = CarBoxWidgetState.isCreativeMode(context);
boolean editing = CarBoxWidgetState.isEditMode(context);
int page  = CarBoxWidgetState.getCurrentPage(context);
int pages = CarBoxWidgetState.getPageCount(context);

State is exposed by a read-only ContentProvider. Every SDK query is defensive and returns the documented fallback when the launcher or provider is unavailable.

Read-only provider URI: content://com.ferra.carboxlauncher.state/config

Intent command = new Intent()
    .putExtra(CarBoxWidgetCommands.EXTRA_COMMAND, "commandName")
    .putExtra(CarBoxWidgetCommands.EXTRA_TEXT, "value");

CarBoxWidgetCommands.sendCommand(context, command);

Full working example: the CarBox Button widget — a fully configurable button (color, background transparency, image, label) where the settings let you pick any of these actions. It's the reference for using the whole API.