Getting Started with TotalCross: A Beginner’s Guide

Getting Started with TotalCross: A Beginner’s Guide

TotalCross is an open-source, Java-based framework for building cross-platform mobile, desktop, and embedded user interfaces using a single codebase. This guide walks you through the essentials to set up your environment, create a simple app, understand core concepts, and prepare for real-world development.

What you’ll need

• Java JDK 11 or later installed and configured in PATH
• A code editor or IDE (IntelliJ IDEA, Eclipse, or VS Code)
• TotalCross SDK (download or add via Maven/Gradle)
• An Android device/emulator or desktop target for testing

Install TotalCross

1. Download the TotalCross SDK or add the dependency:
   • Gradle:

   Code
   Copy CodeCopied
   repositories { mavenCentral() } dependencies { implementation ‘org.totalcross:totalcross:6.00’ } 

   • Maven: add the corresponding org.totalcross dependency to your pom.xml.
2. If targeting Android, install Android SDK and configure an emulator or enable USB debugging on a device.
3. Verify installation by running a sample TotalCross app from the SDK or your IDE.

Project structure and core concepts

• Main class (App): Your app extends TotalCrossApplication or uses MainWindow depending on the version. This is the entry point where UI initialization occurs.
• Controls: UI elements such as Button, Label, Edit, Container, and Image.
• Layouts: Containers use layout managers (e.g., Border, Row, Column) to arrange controls.
• Resources: Images and styles bundled with the app; use TotalCross resource utilities to load them.
• Events: Use listeners (e.g., addPressListener) to respond to user actions.

Create a simple “Hello, TotalCross” app

1. Create a new Java class extending TotalCrossApplication:

Code
Copy CodeCopied
public class HelloApp extends TotalCrossApplication { @Override   public void initUI() {

 
Container c = new Container(new ColumnLayout()); c.add(new Label("Hello, TotalCross!")); Button b = new Button("Click me"); b.addPressListener( e -> Label.info("Button pressed!") ); c.add(b); setContent(c); 
} } 


Build and run for your chosen target (desktop or Android). You should see the label and button; tapping the button shows a brief info message.

Debugging and hot reload tips

Use IDE breakpoints and logging (System.out/TotalCross logging) for debugging.
Desktop runs are faster for UI iteration—test core UI locally, then validate on mobile.
Keep UI logic separate from business logic to simplify testing.

Packaging and deployment

For Android: generate an APK using Gradle or the TotalCross toolchain, sign it, and install to device/emulator.
For desktop: create native bundles or run as a Java application.
For embedded targets: follow device-specific packaging instructions in the TotalCross docs.

Performance and best practices

Reuse UI components and avoid creating heavy objects inside paint/update loops.
Prefer lightweight images and compress assets for mobile.
Minimize synchronous blocking on the UI thread—use background threads for I/O.
Profile memory and CPU on target devices, not just desktop.

Next steps and learning resources

Explore official TotalCross tutorials and sample projects for components and layouts.
Study platform-specific guides for Android packaging and permissions.
Build small projects: a to-do list, simple form app, or settings screen to practice layouts, persistence, and navigation.

This guide gives the minimal essentials to begin with TotalCross. Start a small project, iterate on device, and consult the TotalCross docs and community for advanced topics like custom controls, theming, and embedded targets.