FAQ — Frequently Asked Questions

Answers in one or two sentences, always with a link to the source. To learn, see learn/; to fix an error, see troubleshooting/.

General

What is CrossFly? A UI framework in Java on top of libGDX/OpenGL — it draws everything via the GPU, with no native widgets, so the look is identical on every platform. (Ch. 1)

Do I need to know libGDX? Not for day-to-day work — you work with Window/Component. (Ch. 4)

Bootstrap and lifecycle

How does the app start? The Main instantiates the MainWindow via reflection (using the classname). (Ch. 4)

My MainWindow doesn’t load. It must extend Window and have a public no-args constructor. (Project anatomy)

Where do I build the UI? In onShow() (with super.onShow()), never in the constructor. (Ch. 7)

Threading and rendering

Can I touch the UI from another thread? No — come back with Component.onUI(r) / Main.runOnPaintThread(r). (The paint thread)

I changed something and the screen doesn’t update. Rendering is on demand: call Component.repaint() (and setValidLayout(false) if you changed size/position). (Ch. 4 §4.6)

A long operation without freezing? Run it on a Thread and come back with onUI. (Background work)

Layout

What do the numbers in add() mean? LAY_FILL = -1f fills the remaining space; LAY_AUTO = 0f = content size; >0 = fraction of the container (not pixels). (Ch. 12)

Padding and margin? ingap (inner) and outgap (outer), in the style. (Styling components)

Responsive UI? Use Relative + LAY_FILL/LAY_AUTO, never pixels. (Responsiveness)

GridLayout? Pass all the widths, then all the components: add(w0,w1,…,c0,c1,…). (GridLayout)

How do I navigate between screens? novaWindow.show() = push, hide() = pop (it’s a stack of Window). (Navigation)

Pass data to another screen? Through the constructor of the destination Window — there are no named routes.

Receive a result? picker.show(onAnswer) for pickers; regular screens use a callback through the constructor; Alert responds via buttonAction. (Returning values)

Style, theme, and colors

Switch light/dark? Styles.setDarkMode(true/false) / toggleDarkMode() — it re-skins everything on its own. (Light/dark mode)

Change the Material/iOS “look”? Skin.set(new MaterialSkin()|new IOSSkin()|new FlutterSkin()). (Skins)

Define the colors? Generate a ColorScheme from a seed color. (Color schemes)

My color became invisible. It’s an int ARGB 0xAARRGGBB — without FF in the alpha it disappears. Use 0xFF…. (Ch. 11)

Data and persistence

Save simple preferences? There are no more built-in prefs (Settings.appSettings was removed) — use SQLite or files in Device.homeFolder. (Files and preferences)

Use a database? dev.crossfly.sqlite (SqliteDb/SqliteStmt/SqliteCursor), with SQLite3MC encryption, off the paint thread. (Persistence with SQLite)

Is there a ready-made HTTP/sync client? No — use java.net/OkHttp; JSON with Jackson. (Networking and HTTP)

Text i18n? The framework does not translate — it only formats dates/numbers by locale (LocaleFormats); the translation is yours. (Internationalization)

Large list slow? Use VirtualListView/PagedDataAdapter. (Performance and large lists)

Platforms and device

Which platforms does it run on? Android, iOS, Desktop (Windows/macOS/Linux via LWJGL3) and Web (TeaVM). (Platform matrix)

Camera/GPS/Bluetooth/biometrics? The dev.crossfly.device package; Bluetooth is asynchronous BLE/GATT. (Ch. 24)

Thermal printer? Support removed — talk directly via BLE/GATT. (Bluetooth BLE)

UI stutters on an old device? Check Screen.slowGPU and reduce shadows/gradients/glass. (Ch. 8)

Test the UI automatically? The dev.crossfly.test framework (TestCase + screenshot comparison). (Testing)

The Javadoc contradicts the behavior? Trust the code and this documentation. (How the reference is organized)