# Telamon Framework

> The shared base of every Telamon app, with the Telamon.Ui QML controls, the icon fonts, the Rust crates for startup, settings, logging and system work, and the app template.

Telamon Framework is what every Telamon app is built on, so they all look and behave the same. Telamon OS installs it once and every app uses that copy. It runs on Qt 6.11 and KDE Frameworks 6 on Fedora 44.

## Which library to use

| You want to | Use |
|---|---|
| Build the app's interface: windows, pages, buttons, fields, lists, tables, dialogs, charts | [Telamon.Ui](https://telamon.eterneon.net/framework/telamon-ui.md), the QML module (`import Telamon.Ui`) |
| Show an icon | [Symbols](https://telamon.eterneon.net/framework/symbols.md): `Symbol { icon: Symbols.Home }` draws Material Symbols |
| Name the app, read its settings file, log to the journal | [telamon-framework-core](https://telamon.eterneon.net/framework/telamon-framework-core.md) |
| Start a GUI app: app ID, one instance per session, crash hooks, the Telamon.Ui version check | [telamon-framework-ui](https://telamon.eterneon.net/framework/telamon-framework-ui.md) |
| System work: crash reports, update history, bootc state, polkit checks, desktop notifications | [telamon-framework-system](https://telamon.eterneon.net/framework/telamon-framework-system.md) |
| Flatpak updates | [telamon-framework-flatpak](https://telamon.eterneon.net/framework/telamon-framework-flatpak.md) |
| Start a new app | [The app template](https://telamon.eterneon.net/framework/template.md) |

A small app needs only Telamon.Ui and telamon-framework-ui, which brings in telamon-framework-core. Add the other crates only when the app does that kind of work.

## Getting started

1. Copy the [app template](https://telamon.eterneon.net/framework/template.md) and rename it. It builds on its own: a Rust backend through CXX-Qt, a QML interface on Telamon.Ui, and one line of C++ that starts the app.
2. Build on Fedora 44 with the `telamon-ui` package installed. Telamon.Ui is a QML module next to Qt's own, so the app writes `import Telamon.Ui` and links nothing.
3. Build pages from [TelamonWindow](https://telamon.eterneon.net/framework/telamon-ui/telamon-window.md), [TelamonPage](https://telamon.eterneon.net/framework/telamon-ui/telamon-page.md) and the controls. Colours, spacing, fonts and motion come from [TelamonStyle](https://telamon.eterneon.net/framework/telamon-ui/telamon-style.md), never hard-coded.
4. Run the framework's checks on the app (`tools/lint-app.sh` and `tools/check-app-names.sh` from the framework repository) in its CI.

```qml
import QtQuick
import Telamon.Ui

TelamonWindow {
    title: qsTr("Hello")
    width: 640
    height: 480
    visible: true

    TelamonPage {
        anchors.fill: parent
        title: qsTr("Hello")

        PrimaryButton {
            text: qsTr("Say hello")
            symbol: Symbols.WavingHand
            onClicked: console.log("hello")
        }
    }
}
```

## Versions

Telamon.Ui only ever adds API: a type, property, signal, function, enum value or symbol name is never renamed or removed in a later version. Each page says which version added it (`since`). An app declares the oldest Telamon.Ui it works with (`ui:` in `app!`), and at startup it refuses to run on an older one, with a plain message instead of a broken window.


## Libraries

- [Telamon.Ui](https://telamon.eterneon.net/framework/telamon-ui.md): The QML module every Telamon app imports, with windows, pages, buttons, fields, lists, dialogs, charts and the style and services behind them; how to install it, check it and find a type.
- [Symbols](https://telamon.eterneon.net/framework/symbols.md): Google's Material Symbols as fonts, drawn with the Symbol type and named by Symbols.Name: styles, filled and outline, size, colour and how to find a name.
- [telamon-framework-core](https://telamon.eterneon.net/framework/telamon-framework-core.md): The small Rust crate every Telamon app uses, with app identity, the settings file, journal logging, os-release and a safe append helper, and no Qt or async runtime.
- [telamon-framework-ui](https://telamon.eterneon.net/framework/telamon-framework-ui.md): The Rust crate that starts every Telamon GUI app, with the app! macro, the C functions main.cpp calls, one instance per session, journal logging, crash hooks and the Telamon.Ui version check.
- [telamon-framework-system](https://telamon.eterneon.net/framework/telamon-framework-system.md): The Rust crate for Telamon system apps, with opt-in crash reports, Telamon OS state \(bootc status, boot history, update events\), polkit checks for root helpers and desktop notifications.
- [telamon-framework-flatpak](https://telamon.eterneon.net/framework/telamon-framework-flatpak.md): The Rust crate for Flatpak updates through libflatpak, used by Telamon Updater and the future Telamon Store, with update listing, update runs and a check for newly requested permissions.
- [App template](https://telamon.eterneon.net/framework/template.md): A minimal Telamon app to copy: a Kirigami window on Telamon.Ui, one Rust QObject exposed through CXX-Qt, built with CMake and Corrosion on the framework's crates.