Guia didàctica: Rock, Paper, Scissors amb Configuració

Projecte: A08.04.3_configB
Objectiu: Aprendre gestió moderna de recursos en Qt6 i persistència de dades amb Settings

📚 Índex

Introducció
Què afegeix aquesta versió
Gestió moderna de recursos
Singleton ThemeManager
Persistència amb Settings
Exercicis pràctics

Introducció

Aquest projecte és una evolució del joc Pedra, Paper, Tisores bàsic que ja heu desenvolupat. Afegeix dues funcionalitats importants:

Pantalla de configuració amb tema clar/fosc
Persistència de preferències que es guarden entre sessions

Però el més important: utilitza la gestió moderna de recursos de Qt6, sense fitxers .qrc.

Què afegeix aquesta versió

Versió anterior (A08.04.3)

✅ Joc funcional
✅ Components QML
✅ Recursos amb fitxer .qrc (mètode Qt5)
❌ Sense configuració
❌ Sense persistència

Versió actual (A08.04.3_configB)

✅ Joc funcional
✅ Components QML
✅ Recursos al CMakeLists.txt (mètode Qt6 modern)
✅ Pantalla de configuració
✅ Tema clar/fosc amb ThemeManager singleton
✅ Persistència amb Settings

Gestió moderna de recursos

Per què no usar fitxers .qrc?

El fitxer .qrc és un fitxer XML que Qt5 utilitzava per gestionar recursos:

<!-- qml.qrc - Mètode ANTIC (Qt5) -->
<RCC>
    <qresource prefix="/">
        <file>main.qml</file>
        <file>img/rock.png</file>
        <file>img/paper.png</file>
    </qresource>
</RCC>

Problemes:

❌ Fitxer XML extra a mantenir
❌ Duplicació (has de llistar fitxers al .qrc I al CMakeLists.txt)
❌ Menys integració amb el sistema de mòduls QML de Qt6
❌ Paths llargs i confusos

Mètode modern: CMakeLists.txt

En Qt6, declarem els recursos directament al CMakeLists.txt:

qt_add_qml_module(rps-config
    URI rpsconfig              # Nom del mòdul
    VERSION 1.0                # Versió
    QML_FILES                  # Fitxers QML
        main.qml
        ThemeManager.qml
        BotoRPS.qml
        PaginaJoc.qml
        ConfigPage.qml
        ControlButtons.qml
        VistaJugada.qml
    RESOURCES                  # Recursos (imatges, fonts, etc.)
        img/rock.png
        img/paper.png
        img/scissors.png
        img/settings.png
        img/save.png
)

Avantatges:

✅ Tot en un sol lloc
✅ Més net i mantenible
✅ Millor integració amb Qt6
✅ Paths més curts als QML

On acaben els recursos?

Quan compiles, Qt crea aquesta estructura:

build/
└── rpsconfig/              # Nom del mòdul (URI)
    ├── main.qml
    ├── ThemeManager.qml
    ├── BotoRPS.qml
    ├── img/
    │   ├── rock.png
    │   └── paper.png
    └── qmldir            # Generat automàticament

Els recursos s'encasten dins de l'executable i estan disponibles amb paths com:

Path complet: qrc:/qt/qml/rpsconfig/img/rock.png
Path relatiu (dins del mòdul): img/rock.png ← Recomanat

Paths relatius vs absoluts

❌ MALAMENT: Path sense qrc:/ (no funciona en executable)

Image {
    source: "rock.png"  // Busca al sistema de fitxers
}

Problema: Funciona durant el desenvolupament però NO en l'executable distribuït.

✅ BÉ: Path relatiu dins del mòdul

Image {
    source: "img/rock.png"  // Path relatiu al mòdul
}

Avantatge: Curt, net, funciona sempre.

✅ També BÉ: Path absolut amb qrc:/

Image {
    source: "qrc:/qt/qml/rpsconfig/img/rock.png"  // Path complet
}

Avantatge: Explícit, funciona des de qualsevol lloc.
Desavantatge: Llarg i menys llegible.

Comparació pràctica

Mètode	Path al QML	Funciona en executable?	Recomanat
Sense qrc:/	`"rock.png"`	❌ NO	Mai
Relatiu (mòdul)	`"img/rock.png"`	✅ SÍ	Sí
Absolut	`"qrc:/qt/qml/rpsconfig/img/rock.png"`	✅ SÍ	Si cal

Exemple complet

CMakeLists.txt:

qt_add_qml_module(rps-config
    URI rpsconfig
    QML_FILES BotoRPS.qml
    RESOURCES img/rock.png
)

BotoRPS.qml:

import QtQuick

Item {
    property string font  // Rebem el path de la imatge
    
    Image {
        source: font  // "img/rock.png" (path relatiu)
        anchors.centerIn: parent
        fillMode: Image.PreserveAspectFit
    }
}

ControlButtons.qml:

Repeater {
    model: [
        {tipus: "R", font: "img/rock.png"},      // Path relatiu
        {tipus: "P", font: "img/paper.png"},
        {tipus: "S", font: "img/scissors.png"}
    ]
    
    BotoRPS {
        text: modelData.tipus
        font: modelData.font  // Passa el path al component
    }
}

Singleton ThemeManager

Què és un singleton?

Un singleton és un objecte que:

Existeix una sola instància a tota l'aplicació
És accessible globalment des de qualsevol fitxer QML
Manté un estat compartit

Exemple d'ús: Gestionar el tema (clar/fosc) de tota l'aplicació des d'un sol lloc.

Per què usar un singleton per al tema?

Imagina que vols canviar el color de fons de l'aplicació:

❌ MALAMENT: Sense singleton

// PaginaJoc.qml
Rectangle {
    color: root.isDark ? "#1E1E1E" : "#FFFFFF"  // Duplicat!
}

// ConfigPage.qml
Rectangle {
    color: root.isDark ? "#1E1E1E" : "#FFFFFF"  // Duplicat!
}

// BotoRPS.qml
Rectangle {
    color: root.isDark ? "#2D2D2D" : "#F5F5F5"  // Més duplicació!
}

Problemes:

Codi duplicat a tots els fitxers
Difícil de mantenir (has de canviar-ho a tots els llocs)
Propietats que has de passar entre components

✅ BÉ: Amb singleton

// PaginaJoc.qml
Rectangle {
    color: ThemeManager.backgroundColor  // Centralitzat!
}

// ConfigPage.qml
Rectangle {
    color: ThemeManager.backgroundColor  // Mateix codi!
}

// Canviar el tema des de qualsevol lloc:
Button {
    onClicked: ThemeManager.toggleTheme()
}

Com crear un singleton

1. Crear el fitxer QML amb `pragma Singleton`

ThemeManager.qml:

pragma Singleton  // ← IMPORTANT: Declara que és singleton
import QtQuick

QtObject {
    id: themeManager
    
    // Propietat principal
    property bool darkMode: false
    
    // Colors mode clar
    property color lightBackground: "#FFFFFF"
    property color lightText: "#000000"
    
    // Colors mode fosc
    property color darkBackground: "#1E1E1E"
    property color darkText: "#FFFFFF"
    
    // Colors actius (calculats segons darkMode)
    property color backgroundColor: darkMode ? darkBackground : lightBackground
    property color textColor: darkMode ? darkText : lightText
    
    // Funció per canviar el tema
    function toggleTheme() {
        darkMode = !darkMode
    }
}

2. Declarar-lo al fitxer qmldir

qmldir:

module rpsconfig
singleton ThemeManager 1.0 ThemeManager.qml

Sintaxi:

module rpsconfig - Nom del mòdul (ha de coincidir amb URI al CMakeLists.txt)
singleton - Paraula clau que indica que és un singleton
ThemeManager - Nom amb què s'accedeix des dels QML
1.0 - Versió
ThemeManager.qml - Fitxer font

3. Usar-lo als fitxers QML

import rpsconfig  // Importa el mòdul

Rectangle {
    color: ThemeManager.backgroundColor  // Accés directe
    
    Text {
        color: ThemeManager.textColor
        text: "Hola món"
    }
    
    Button {
        text: "Canviar tema"
        onClicked: ThemeManager.toggleTheme()
    }
}

Com funciona internament?

Compilació: CMake i Qt generen codi C++ que registra el singleton
Execució: Qt crea una única instància de ThemeManager
Accés: Tots els fitxers QML comparteixen la mateixa instància

┌─────────────────┐
│  ThemeManager   │  ← Una sola instància
│  (Singleton)    │
└────────┬────────┘
         │
    ┌────┴────┬────────┬────────┐
    │         │        │        │
PaginaJoc  ConfigPage  Botons  etc.
    │         │        │        │
 Accedeixen a la mateixa instància

Propietats reactives

Quan canvies darkMode, tots els colors s'actualitzen automàticament:

property color backgroundColor: darkMode ? darkBackground : lightBackground
//                              ↑ Quan darkMode canvia, aquesta expressió
//                                es recalcula automàticament

Això s'anomena binding en Qt:

Les propietats es recalculen quan les seves dependències canvien
No cal codi extra per actualitzar la UI

Persistència amb Settings

Què és Qt.labs.settings?

Qt.labs.settings és un component QML que:

Guarda dades automàticament quan canvien
Carrega dades automàticament quan l'aplicació s'inicia
Multiplataforma: funciona a Linux, Windows, macOS, Android

On es guarden les dades?

Plataforma	Ubicació
Linux	`~/.config/ExempleOrg/RPSConfig.conf`
macOS	`~/Library/Preferences/cat.exemple.RPSConfig.plist`
Windows	Registre: `HKEY_CURRENT_USER\Software\ExempleOrg\RPSConfig`
Android	`SharedPreferences` intern

Configurar l'organització i aplicació

main.cpp:

#include <QGuiApplication>
#include <QQmlApplicationEngine>

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    // IMPORTANT: Defineix organització i aplicació
    QCoreApplication::setOrganizationName("ExempleOrg");
    QCoreApplication::setOrganizationDomain("exemple.cat");
    QCoreApplication::setApplicationName("RPSConfig");
    
    // Sense això, Settings no sap on guardar les dades!

    QQmlApplicationEngine engine;
    engine.loadFromModule("rpsconfig", "Main");

    return app.exec();
}

Usar Settings al QML

main.qml:

import QtQuick
import Qt.labs.settings 1.0  // Importa Settings

ApplicationWindow {
    id: root
    
    // Dades locals de l'aplicació
    property bool soundEnabled: true
    property int gamesPlayed: 0
    
    // Settings: guarda automàticament
    Settings {
        // property alias NOM_SETTING: objecte.propietat
        property alias darkMode: ThemeManager.darkMode
        property alias sound: root.soundEnabled
        property alias games: root.gamesPlayed
    }
    
    // Quan darkMode canvia → es guarda automàticament
    // Quan l'app s'inicia → es carrega automàticament
}

Com funciona Settings?

Inici de l'aplicació:
1. Qt carrega Settings des del disc
2. Assigna valors a les propietats (darkMode, soundEnabled, etc.)
3. L'app continua amb els valors restaurats

Durant l'execució:
1. L'usuari canvia darkMode = true
2. Settings detecta el canvi
3. Guarda automàticament al disc

Tancament de l'aplicació:
1. Settings guarda tots els canvis pendents
2. L'app es tanca

Exemple complet

ConfigPage.qml:

import QtQuick
import QtQuick.Controls
import rpsconfig

Page {
    Column {
        spacing: 20
        
        // Switch per al tema
        Switch {
            text: "Mode fosc"
            checked: ThemeManager.darkMode
            
            onToggled: {
                ThemeManager.toggleTheme()
                // Settings guarda automàticament!
            }
        }
        
        // Switch per al so
        Switch {
            text: "So activat"
            checked: root.soundEnabled
            
            onToggled: {
                root.soundEnabled = checked
                // Settings guarda automàticament!
            }
        }
        
        Text {
            text: "Partides jugades: " + root.gamesPlayed
            color: ThemeManager.textColor
        }
    }
}

Verificar que funciona

Executa l'aplicació
Canvia el tema a fosc
Tanca l'aplicació
Torna a obrir-la
✅ El tema hauria de seguir sent fosc!

Veure el fitxer de configuració (Linux)

# Mostra el contingut del fitxer de configuració
cat ~/.config/ExempleOrg/RPSConfig.conf

Veuràs alguna cosa com:

[General]
darkMode=true
sound=true
games=5

Consells pràctics

Usa alias sempre que sigui possible

Settings {
    property alias darkMode: ThemeManager.darkMode  // Millor
    // En comptes de:
    // property bool darkMode: ThemeManager.darkMode  // Pitjor
}

Agrupa settings relacionades

Settings {
    category: "Appearance"  // Grup al fitxer de configuració
    property alias darkMode: ThemeManager.darkMode
    property alias fontSize: root.fontSize
}

Settings {
    category: "Game"
    property alias difficulty: root.difficulty
    property alias gamesPlayed: root.gamesPlayed
}

Proporciona valors per defecte

property bool soundEnabled: true  // Valor per defecte si no hi ha Settings

Settings {
    property alias sound: root.soundEnabled
}

Recursos addicionals

Documentació oficial Qt6

Bones pràctiques

Usa singletons per a estat global (temes, configuració, etc.)
Usa Settings per a persistència (preferències de l'usuari)
Usa paths relatius per a recursos dins del mòdul
Separa lògica de vista (components reutilitzables)
Fes Clean + Rebuild després de canvis en recursos

Errors comuns

Error	Causa	Solució
"Cannot open: img/rock.png"	Recursos no al CMakeLists.txt	Afegeix-los a `RESOURCES`
"ThemeManager is not defined"	Falta declaració singleton	Afegeix al `qmldir`
"Settings no guarda"	Falta setOrganizationName	Afegeix al `main.cpp`
Colors [undefined]	ThemeManager no és singleton	Verifica `pragma Singleton`

Resum

Has après:

✅ Gestió moderna de recursos sense fitxers .qrc
✅ Paths relatius dins de mòduls QML
✅ Singletons per a estat global compartit
✅ Persistència automàtica amb Settings
✅ Arquitectura modular amb components reutilitzables

Pròxims passos:

Completa els exercicis pràctics
Experimenta amb més funcionalitats de Settings
Crea els teus propis singletons per a altres casos d'ús
Aplica aquests conceptes als teus projectes

Molt bé! Ara tens tots els coneixements per crear aplicacions Qt6 modernes amb gestió de recursos i persistència de dades. 🎉

Guia didàctica: Rock, Paper, Scissors amb Configuració

📚 Índex

Introducció

Què afegeix aquesta versió

Versió anterior (A08.04.3)

Versió actual (A08.04.3_configB)

Gestió moderna de recursos

Per què no usar fitxers .qrc?

Mètode modern: CMakeLists.txt

On acaben els recursos?

Paths relatius vs absoluts

❌ MALAMENT: Path sense qrc:/ (no funciona en executable)

✅ BÉ: Path relatiu dins del mòdul

✅ També BÉ: Path absolut amb qrc:/

Comparació pràctica

Exemple complet

Singleton ThemeManager

Què és un singleton?

Per què usar un singleton per al tema?

❌ MALAMENT: Sense singleton

✅ BÉ: Amb singleton

Com crear un singleton

1. Crear el fitxer QML amb pragma Singleton

2. Declarar-lo al fitxer qmldir

3. Usar-lo als fitxers QML

Com funciona internament?

Propietats reactives

Persistència amb Settings

Què és Qt.labs.settings?

On es guarden les dades?

Configurar l'organització i aplicació

Usar Settings al QML

Com funciona Settings?

Exemple complet

Verificar que funciona

Veure el fitxer de configuració (Linux)

Consells pràctics

Recursos addicionals

Documentació oficial Qt6

Bones pràctiques

Errors comuns

Resum

Has après:

Pròxims passos:

1. Crear el fitxer QML amb `pragma Singleton`