Skip to content
Telamon OSFramework API
Browse the docs

Telamon.Ui

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.

Telamon.Ui is the QML module of Telamon controls. Every Telamon app imports it, so they all share one look, one set of keyboard and accessibility rules and one copy on disk. It is a QML module installed next to Qt's own, like Kirigami. Its URI is Telamon.Ui.

Install and import

Install the telamon-ui package (Fedora 44, Qt 6.11). It brings in the Material Symbols fonts (telamon-symbols-fonts), Kirigami, IBM Plex Sans and JetBrains Mono.

sudo dnf install telamon-ui

The module lives in Qt's QML directory (/usr/lib64/qt6/qml/Telamon/Ui/). An app writes import Telamon.Ui in QML and links nothing: the QML engine loads the plugin. There is no CMake package and no devel package.

import QtQuick
import Telamon.Ui

TelamonWindow {
    title: qsTr("Hello")
    visible: true

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

        PrimaryButton {
            text: qsTr("Say hello")
            symbol: Symbols.WavingHand
        }
    }
}

Note

import Telamon.Ui wins over the QML files in an app's own directory. An app file named like a Telamon.Ui type (say SearchField.qml) is hidden by it. New Telamon.Ui types are named Telamon<Name> to keep clear of apps' names; see Compatibility.

Check the module at configure time

The app template fails the CMake configure with a plain message when the module is missing. qmlcachegen and qmllint find it in Qt's QML directory by themselves, so the app's <app>_qmllint target checks the app's QML against it.

if(NOT EXISTS "${QT6_INSTALL_PREFIX}/${QT6_INSTALL_QML}/Telamon/Ui/qmldir")
    message(FATAL_ERROR "Telamon.Ui is not installed: dnf install telamon-ui")
endif()

Version rule

Telamon.Ui only ever adds API. An app that uses something added after 1.0.0 states the oldest version it works with in two places, and keeps them equal:

  • Requires: telamon-ui >= X.Y.Z (and BuildRequires) in the app's RPM spec, so dnf installs a new enough one;
  • ui: "X.Y.Z" in the app's app! call, so at startup an older Telamon.Ui, installed some other way, gives a plain error window instead of a broken one.

TelamonApp.uiVersion reports the installed version at run time. Each page says which version added its type (since).

Guides

  • Design rules: what every Telamon app does.
  • Style and theming: colours, spacing, radii, density, blur and text scale.
  • Motion: springs, reduced motion and the violet to sakura gradient.
  • Compatibility: the API contract and what it means for an app.
  • Accessibility: focus, roles, names, right-to-left and the framework's tests.

The types

Every type has a page. The groups below are the sidebar sections.

Windows and pages

  • TelamonWindow: The application window: blurred or opaque by the shared switch, remembers its size, and goes frameless with a header bar.
  • TelamonHeaderBar: The merged header of a frameless window: window menu, title, tools and window buttons.
  • TelamonWindowButtons: Minimise, maximise and close buttons drawn like the Telamon OS window decoration.
  • TelamonWindowChrome: Singleton with the desktop's caption-button layout and whether a global menu exists.
  • TelamonPage: A scrolling page with a large bold title and centred margins.
  • TelamonAboutPage: A ready-made About page for any app.
  • TelamonOnboarding: A setup scaffold: steps, one page at a time, Back, Skip and Next.
  • StatusBar: A slim bottom bar of cells such as line, column and encoding.
  • StatusBarItem: One cell of a status bar, optionally clickable or with a menu.

Buttons

Fields and pickers

Lists and tables

Feedback and status

  • InfoBanner: An inline info, warning or error banner with actions.
  • Toast: A short message that goes by itself.
  • TelamonProgressBar: A progress bar with indeterminate, paused and error states.
  • TelamonSpinner: A busy indicator.
  • TelamonPlaceholder: Skeleton bars shown while content loads.
  • TelamonEmptyState: What a list shows when it has nothing.
  • TelamonStatus: Loading, Empty, NoResults and Error for lists, tables, trees and pages.
  • TelamonBadge: A small pill label for a status or count.
  • TelamonAvatar: A round picture of a person, with initials as the fallback.
  • TelamonStat: A figure with a label, a unit, a trend and a sparkline.
  • TelamonEdgeGlow: The violet-to-sakura glow for "the system is working for you now".
  • StatusHero: A big centred status: icon, headline, subtitle and actions.

Charts

Text and code

Layout

Style and motion

Icons

  • Symbol: One Material Symbols icon.
  • Symbols: The singleton of every symbol's name.

Services

Validators

Pages