# atlas-framework-ui

> The Rust crate that starts every Atlas GUI app, with the app! macro, the C functions main.cpp calls, one instance per session, journal logging, crash hooks and the Atlas.Ui version check.

`atlas-framework-ui` starts an Atlas app so the app's own code is only what makes it different. The app's Rust library names the app once with [`app!`](https://atlasos.eterneon.net/framework/atlas-framework-ui/app-macro.md), and its `main.cpp` makes one call into the [C API](https://atlasos.eterneon.net/framework/atlas-framework-ui/c-api.md). Every Atlas app then starts the same way: the app ID as the desktop file name and single-instance D-Bus name, the org.kde.desktop style, [logs in the journal, crash hooks and one instance per session](https://atlasos.eterneon.net/framework/atlas-framework-ui/startup.md), and the names that [AtlasApp](https://atlasos.eterneon.net/framework/atlas-ui/atlas-app.md) and [AtlasAboutPage](https://atlasos.eterneon.net/framework/atlas-ui/atlas-about-page.md) show.

Every GUI app needs it. The look itself is not here: it is the installed [Atlas.Ui](https://atlasos.eterneon.net/framework/atlas-ui.md) QML module.

## Add it

```toml
atlas-framework-ui = { git = "https://github.com/EternalCoder454/atlas-framework", rev = "7a114a112bd1fff4fe3d6facc81b0a81e5d2db30" }
```

The commit is the one tagged `v1.4.0`. Pin apps to a commit or a release tag and build with `cargo build --locked`. Add [atlas-framework-system](https://atlasos.eterneon.net/framework/atlas-framework-system.md) or [atlas-framework-flatpak](https://atlasos.eterneon.net/framework/atlas-framework-flatpak.md) separately only if the app needs them.

The crate builds C++ through CXX-Qt (`cxx-qt-build`, Qt modules Gui, Widgets, Qml, Quick, QuickControls2 and DBus) and links `KF6DBusAddons` and `KF6WindowSystem`. KF6 ships no pkg-config files, so its headers are taken from `/usr/include/KF6`, or from the directory in the `ATLAS_KF6_INCLUDEDIR` environment variable. Corrosion does not pass a crate's native libraries on to the executable, so a CMake app also links `KF6::DBusAddons` and `KF6::WindowSystem` itself (the app template shows it).

## Features

None. The crate depends on atlas-framework-core and atlas-framework-system (without its `polkit` and `notify` features), `log` and `libc`.

## Pages

| Page | What it covers |
|---|---|
| [app!](https://atlasos.eterneon.net/framework/atlas-framework-ui/app-macro.md) | The macro that names the app, every field, and the `ui:` version check |
| [The C API](https://atlasos.eterneon.net/framework/atlas-framework-ui/c-api.md) | `atlas_app_run`, `atlas_app_init`, `atlas_app_ready`, `atlas_app_require_ui` |
| [Startup behaviour](https://atlasos.eterneon.net/framework/atlas-framework-ui/startup.md) | Single instance, activation token, logging, panic and Qt message hooks |

## Crate root

| Name | Kind | Description |
|---|---|---|
| `app!` | macro | Names the app. Use it once in the app's library |
| `AppInfo` | re-export | `atlas_framework_core::AppInfo` |
| `atlas_framework_core` | re-export | The whole core crate |
| `atlas_framework_system` | re-export | The whole system crate (without the optional features) |
| `fn app_info() -> &'static AppInfo` | function | The app, as its `app!` named it |
| `fn required_ui() -> Option<&'static str>` | function | The Atlas.Ui version the app's `app!` asks for (`ui:`), if any |
| `fn start()` | function | Installs the logger and the crash hook. Only the first call does anything |


## Pages

- [app!](https://atlasos.eterneon.net/framework/atlas-framework-ui/app-macro.md): The macro that names an Atlas app once, with its name, ID, repository and optionally the oldest Atlas.Ui it works with.
- [The C API](https://atlasos.eterneon.net/framework/atlas-framework-ui/c-api.md): The C functions in include/atlas/app.h that an app's main.cpp calls to start, with atlas\_app\_run for most apps and atlas\_app\_init and atlas\_app\_ready for apps with their own shell.
- [Startup behaviour](https://atlasos.eterneon.net/framework/atlas-framework-ui/startup.md): What an Atlas app does at start, with one instance per session, the Wayland activation token, journal logging, the Rust panic hook and the fatal Qt message hook.