官网

English

简体中文

English

简体中文

Appearance

UniDesk Control Library Overview ​

UniDesk is a built-in QML control library of Uniquenium, inspired by LingmoUI, providing a set of modern Fluent-style UI controls. Using UniDesk, you can quickly build beautifully designed, uniformly styled desktop application interfaces.

Read the Glossary First

Before starting, it is recommended to read the Glossary to understand the difference between Control and Component. This page introduces "controls" — the most basic elements that make up the interface.

System Requirements ​

Before developing with UniDesk, ensure your environment meets the following requirements:

DependencyMinimum VersionDescription
CMake3.25+Build system
Qt6.5.0+QML engine and Qt Quick (including Core, Widgets, Quick, QuickControls2, etc.)
ECMLatestExtra CMake Modules
C++ CompilerC++17MSVC 2022 / GCC 13+ / Clang 16+

Learning Suggestion

Before starting, it is recommended to read the Qt official QML documentation to understand basic QML syntax and concepts.

Development Environment Setup ​

Step 1: Get the Source Code ​

bash
git clone https://github.com/Uniquenium/Uniquenium.git
cd Uniquenium
git submodule update --init --recursive

Step 2: Configure & Compile ​

bash
# Configure (replace with your Qt6 path)
cmake -B build -DCMAKE_PREFIX_PATH="<Your Qt6 installation path>"

# Compile
cmake --build build --config Release

Step 3: Launch the Program ​

bash
# Windows:
.\build\Release\Uniquenium0.exe --debug

# Linux:
./build/Uniquenium0 --debug

Control Library: UniDesk ​

Module Import ​

Use the following statements at the beginning of QML files to import UniDesk controls:

qml
// Base module (global singletons: UniDeskGlobals, UniDeskTools, UniDeskSettings...)
import UniDesk 1.0

// UI control module (all visual controls including buttons, text, windows)
import UniDesk.Controls 1.0

Control Classification ​

Content in UniDesk is divided into two categories:

CategoryDescriptionNaming PatternExamples
SingletonGlobally unique instances, accessed directly by name for global state and toolsAny global state/toolUniDeskGlobals, UniDeskTools, UniDeskSettings
ControlInstantiable, nestable visual UI elements, the foundation of building componentsUniDesk + control nameUniDeskButton, UniDeskWindow, UniDeskText

Base Classes Removed

Early versions had "base class" concepts like UniDeskBase and UniDeskWindowBase. The current version has removed the base class abstraction layer. All controls now directly inherit from Qt native types (such as Item, Rectangle, Window), without the need for indirect inheritance through base classes. If you see bases-related references in old documentation or code, use this page as the standard.

Using Singletons ​

Singletons are globally unique objects that do not need to be instantiated — they can be accessed directly by name in any QML file.

qml
import UniDesk 1.0
import UniDesk.Controls 1.0

Item {
    Component.onCompleted: {
        // Access properties directly
        console.log("Current theme:", UniDeskGlobals.isLight ? "Light" : "Dark")
        console.log("Theme color:", UniDeskSettings.primaryColor)

        // Call methods directly
        UniDeskTools.web_browse("https://github.com/Uniquenium")
        var uuid = UniDeskTools.createUuid()
    }
}

General format:

qml
<singletonName>.<propertyName>
<singletonName>.<functionName>(parameters)

Using Controls ​

Visual controls are used through QML declarative syntax, supporting properties, signals, and nested children. Controls can be used individually or combined to form more complex "components."

qml
import UniDesk.Controls 1.0

// Parent control
UniDeskWindow {
    id: myWindow
    visible: true
    width: 600
    height: 400
    title: "My Window"

    // Properties
    tintOpacity: 0.85
    showStayTop: true

    // Event (signal) handling
    onActiveChanged: {
        console.log("Window active status:", active)
    }

    // Child controls (nested)
    UniDeskButton {
        id: myBtn
        anchors.centerIn: parent
        contentText: "Click Me"
        iconSource: "qrc:/icon/heart.svg"
        display: Button.TextUnderIcon
        radius: 8

        onClicked: {
            myWindow.showSuccess("Button clicked!", 3000)
        }

        // Nested grandchild control
        UniDeskTooltip {
            text: "This is a button tooltip"
        }
    }
}

General pattern:

qml
<controlName> {
    <propertyName>: <propertyValue>
    <signalName>: { /* handle logic */ }
    <childControlName> { /* ... */ }
}

Built-in Singletons Overview ​

SingletonPurposeCommon Content
UniDeskGlobalsGlobal stateisLight theme mode, event notifications
UniDeskToolsTool functionsColor switching, wallpaper operations, font management, UUID generation
UniDeskSettingsSettings accessprimaryColor theme color, various configuration read/write
UniDeskTextStylePreset fontstiny / little / middle / big four font sizes
UniDeskExprExpression engine%variable substitution, %{} math expressions
UniDeskPluginMgrPlugin managementPlugin loading, unloading, metadata management
UniDeskTempleteMgrTemplate managementTemplate import/export, preset variables
UniDeskComponentsDataComponent dataComponent and page JSON data persistence
UniDeskComManagerComponent managementComponent registration, creation, destruction
UniDeskSettingsWindowSettings windowProgram settings UI entry

Theme Adaptation Best Practices ​

All UniDesk controls have built-in dark/light dual themes, but custom controls require manual adaptation:

qml
import UniDesk 1.0

Rectangle {
    id: myCard
    width: 200
    height: 120
    radius: 8

    // Wrong: hardcoded color
    // color: "white"
    // border.color: "black"

    // Correct: use UniDeskGlobals for dynamic judgment
    color: UniDeskGlobals.isLight
        ? Qt.rgba(255/255, 255/255, 255/255, 1)
        : Qt.rgba(32/255, 32/255, 32/255, 1)

    border.color: UniDeskGlobals.isLight
        ? Qt.rgba(0, 0, 0, 0.1)
        : Qt.rgba(1, 1, 1, 0.1)

    // Accent color always uses theme color
    Rectangle {
        width: 4
        height: parent.height
        color: UniDeskSettings.primaryColor
    }
}

For more precise color control, use UniDeskTools.switchColor():

qml
import UniDesk 1.0

property color textNormalColor: UniDeskGlobals.isLight ? "black" : "white"
property color textHoverColor:  UniDeskGlobals.isLight ? textNormalColor.darker(1.2) : textNormalColor.lighter(1.2)
property color textPressColor:  UniDeskGlobals.isLight ? textNormalColor.darker(1.5) : textNormalColor.lighter(1.5)
property color textDisableColor: "#888888"

property color finalColor: UniDeskTools.switchColor(
    textNormalColor, textHoverColor, textPressColor, textDisableColor,
    hovered, pressed, disabled
)

Control Documentation Index ​

View detailed API documentation for each control by functional category:

Singletons ​

Windows & Containers ​

Button Controls ​

Input Controls ​

Selection Controls ​

Text & Display ​

Position & Size Selection ​

Component Editor Specific ​

Base Object ​

Next Steps ​

Released under the CC BY-SA 4.0 open documentation license.

Copyright © 2025-present Uniquenium Development Team · Crafted with care