Design the entire CarBox home in Android Studio.

android {
  namespace 'com.example.carbox.theme'
  compileSdk 34

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

<resources>
    <string name="app_name">My CarBox Theme</string>
    <string name="theme_name">MY THEME</string>
    <string name="open_drawer">Open drawer</string>
    <string name="close_drawer">Close drawer</string>
</resources>

<resources>
    <string name="app_name">Mio tema CarBox</string>
    <string name="theme_name">MIO TEMA</string>
    <string name="open_drawer">Apri cassetto</string>
    <string name="close_drawer">Chiudi cassetto</string>
</resources>

// Android automatically selects the right strings.xml based on device language
String openLabel = getString(R.string.open_drawer);  // "Open drawer" or "Apri cassetto"
String themeName = getString(R.string.theme_name);

TextView header = findViewById(R.id.header);
header.setText(getString(R.string.theme_name));  // Automatically localized

public final class MyThemeActivity
    extends CarBoxThemeActivity {
  @Override
  protected void onCreate(Bundle state) {
    super.onCreate(state);
    setContentView(R.layout.theme_main);
    bindPanelArea(R.id.carboxPanelArea);
  }
}

carBox().launchApp("com.spotify.music", CarBoxTarget.LEFT_PANEL);
carBox().launchApp("com.spotify.music", CarBoxTarget.RIGHT_PANEL);
carBox().launchApp("com.spotify.music", CarBoxTarget.FULLSCREEN);

carBox().openDrawer();          // app drawer
carBox().openPhone();           // phone / dialer
carBox().openContacts();        // contacts
carBox().openNotifications();   // notifications panel
carBox().openSettings();        // launcher settings
carBox().openAssistant();       // voice assistant
carBox().goHome();              // back to launcher home

carBox().openCreativeMode();    // switch to creative mode
carBox().restartLauncher();     // restart the launcher process
carBox().reloadPanels();        // re-render dual-app panels

// Legacy VD path only: reports the DualApp rect to CarBox.
// Plugin v2: skip this — the launcher inserts panels into getPanelHost().
carBox().reportPanelArea(new Rect(0, 0, 800, 480));

carBox().hidePanelHandles();
carBox().showPanelHandles();
carBox().setPanelHandlesVisible(false);
carBox().togglePanelHandles();

// Same behaviour as tapping the launcher's bottom handles.
// A second call restores the saved split ratio.
carBox().expandLeftPanel();
carBox().expandRightPanel();

// New in launcher 1.75+. Read the CURRENT left-panel fraction (0..1) so a
// theme can save "user pinned panels at 70/30" as part of a preset.
// Falls back to 0.5 if the launcher is older or the panels are not ready.
float ratio = carBox().getPanelSplitRatio();

// Restore the exact split when the user re-applies a saved preset.
// Range is clamped to [0.15, 0.85] on the launcher side (safety, no tiny panels).
// The launcher debounces rapid calls (120 ms) so rebuilding a whole preset in a loop is safe.
carBox().setPanelSplitRatio(0.7f);   // 70% left, 30% right

// Dual-app panels sit above the launcher window and cover normal dialogs.
// Call setDialogMode(true) BEFORE showing a dialog and false when it dismisses:
// CarBox will move the panels aside without suspending the running apps.
carBox().setDialogMode(true);
dialog.setOnDismissListener(d -> carBox().setDialogMode(false));
dialog.show();

if (carBox().isHosted(this)) {
    // running inside CarBox: bridge commands are active
} else {
    // running standalone (preview mode): commands are no-ops
}

private SharedPreferences prefs;

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

    // Accedi alle prefs DOPO attachHostActivity (launcher context)
    prefs = getSharedPreferences("theme_prefs", Context.MODE_PRIVATE);

    // Leggi impostazioni salvate
    int dockHeight = prefs.getInt("dock_height_dp", 56);
    int dockColor = prefs.getInt("dock_color", 0xE6111B24);

    // Salva impostazioni
    prefs.edit()
        .putInt("dock_height_dp", 64)
        .putInt("dock_color", 0xFF1E88E5)
        .putStringSet("visible_icons", new HashSet<>(Arrays.asList("phone", "apps")))
        .apply();
}

// AndroidManifest.xml
<activity
    android:name=".SettingsActivity"
    android:label="Theme Settings"
    android:theme="@style/Theme.MyTheme.Settings">
    <intent-filter>
        <action android:name="com.ferra.carboxlauncher.action.THEME_SETTINGS" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

// SettingsActivity.java
public class SettingsActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        SharedPreferences prefs = getSharedPreferences("theme_prefs", MODE_PRIVATE);

        // Color picker
        findViewById(R.id.dock_color_btn).setOnClickListener(v -> {
            showColorPicker(prefs, "dock_color", 0xE6111B24);
        });

        // Dock height slider
        SeekBar dockHeightSlider = findViewById(R.id.dock_height);
        dockHeightSlider.setProgress(prefs.getInt("dock_height_dp", 56));
        dockHeightSlider.setOnSeekBarChangeListener(new SeekBar.OnSeekBarChangeListener() {
            @Override
            public void onProgressChanged(SeekBar seekBar, int progress, boolean fromUser) {
                prefs.edit().putInt("dock_height_dp", Math.max(44, Math.min(84, progress))).apply();
            }
        });
    }
}

// Request location + weather API
private void fetchWeather(double lat, double lon) {
    new Thread(() -> {
        try {
            URL url = new URL("https://api.open-meteo.com/v1/forecast?latitude="
                + lat + "&longitude=" + lon
                + "¤t_weather=true&temperature_unit=celsius");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            BufferedReader reader = new BufferedReader(new InputStreamReader(conn.getInputStream()));

            JSONObject response = new JSONObject(reader.readLine());
            JSONObject current = response.getJSONObject("current_weather");
            double temp = current.getDouble("temperature");

            runOnUiThread(() -> {
                TextView weatherView = findViewById(R.id.weather);
                weatherView.setText(String.format("%.1f°C", temp));
            });
        } catch (Exception e) {
            Log.e("Weather", "Error fetching weather", e);
        }
    }).start();
}

// Listen to media session callbacks
private void setupNowPlayingBar() {
    findViewById(R.id.now_playing_toggle).setOnClickListener(v -> {
        boolean isOpen = prefs.getBoolean("now_playing_open", false);
        prefs.edit().putBoolean("now_playing_open", !isOpen).apply();

        // Expand/collapse sidebar (280dp wide)
        FrameLayout nowPlaying = findViewById(R.id.now_playing_sidebar);
        TransitionManager.beginDelayedTransition(nowPlaying);
        nowPlaying.getLayoutParams().width = isOpen ? 0 : dpToPx(280);
        nowPlaying.setLayoutParams(nowPlaying.getLayoutParams());
    });
}

// Store visible icons as JSON array
private void saveIconOrder(List<String> iconIds) {
    JSONArray arr = new JSONArray(iconIds);
    prefs.edit().putString("dock_icon_order", arr.toString()).apply();
}

// Load and apply saved order
private List<String> loadIconOrder() {
    String json = prefs.getString("dock_icon_order", "[]");
    List<String> icons = new ArrayList<>();
    try {
        JSONArray arr = new JSONArray(json);
        for (int i = 0; i < arr.length(); i++) {
            icons.add(arr.getString(i));
        }
    } catch (JSONException e) {
        Log.e("IconOrder", "Error parsing icon order", e);
    }
    return icons;
}

// Check if icon should be visible
private boolean isIconVisible(String iconId) {
    return prefs.getBoolean("dock_icon_visible_" + iconId, true);
}

private void applyThemeColors() {
    int dockColor = prefs.getInt("dock_color", 0xE6111B24);
    int iconColor = prefs.getInt("icon_color", 0xFFE8F4F8);

    findViewById(R.id.dock_bar).setBackgroundColor(dockColor);

    ViewGroup iconContainer = findViewById(R.id.icon_container);
    for (int i = 0; i < iconContainer.getChildCount(); i++) {
        ImageView icon = (ImageView) iconContainer.getChildAt(i);
        icon.setColorFilter(iconColor, PorterDuff.Mode.SRC_IN);
    }
}

public class MyThemeActivity extends CarBoxThemeActivity {
  @Override
  protected void onCreate(Bundle state) {
    super.onCreate(state);
    setContentView(R.layout.theme_main);
    // The bridge is initialized with a unique session token
    // Every command includes this token for validation
    bindPanelArea(R.id.carboxPanelArea);
  }
}

// This does NOT run launcher code in your process.
// CarBox receives the broadcast, validates the token, and executes safely.
carBox().launchApp("com.spotify.music", CarBoxTarget.LEFT_PANEL);

// Under the hood:
// 1. Theme sends explicit broadcast with EXTRA_TOKEN
// 2. Launcher validates token matches current session
// 3. Launcher executes the action in its own process
// 4. Token becomes invalid when theme closes

// If the token is invalid, the command fails silently.
// If the launcher crashes, the theme continues running
// (it won't inherit launcher privileges and crash with it).
try {
  if (carBox().isHosted(this)) {
    // Bridge is active, commands work
    carBox().openDrawer();
  } else {
    // Preview mode or launcher offline
    Toast.makeText(this, "Not running in CarBox", Toast.LENGTH_SHORT).show();
  }
} catch (Exception e) {
  // Commands never throw; they fail gracefully
}

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

$env:JAVA_HOME = 'C:\Program Files\Android\Android Studio\jbr'
.\gradlew.bat :app:assembleDebug

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

# keystore.properties (root, git-ignored) — set your own values
storeFile=..\\..\\release_key.jks
storePassword=***
keyAlias=upload
keyPassword=***

# app/build.gradle — enable release signing
signingConfigs {
  release {
    def props = new Properties()
    file('../keystore.properties').withInputStream { props.load(it) }
    storeFile     file(props['storeFile'])
    storePassword props['storePassword']
    keyAlias      props['keyAlias']
    keyPassword   props['keyPassword']
  }
}
buildTypes { release { signingConfig signingConfigs.release; minifyEnabled false } }

# build the .aab to upload to Play Console
.\gradlew.bat :app:bundleRelease

# Identity
package_name        = com.example.mytheme
theme_id            = my_theme            # immutable, internal
play_store_url      = https://play.google.com/store/apps/details?id=com.example.mytheme

# Card metadata (EN + IT)
name_en / name_it
description_en / description_it
author

# Versioning (MUST match Google Play)
version_name         = 1.0.0
version_code         = 1                  # drives the "update available" badge
min_launcher_version = 1

# Pricing (label only — real price on Play)
price_type          = free | paid
price_string        = "€2.99"             # optional display label

# Media
preview             = screenshot PNG/JPG/WebP
icon                = 512×512 PNG