diff --git a/Writerside/topics/Suyu-GUI-Framework.md b/Writerside/topics/Suyu-GUI-Framework.md index 3b5f83b..6710b91 100644 --- a/Writerside/topics/Suyu-GUI-Framework.md +++ b/Writerside/topics/Suyu-GUI-Framework.md @@ -1,6 +1,6 @@ # Suyu-GUI-Framework -This document provides information for developers who want to contribute to the Suyu emulator project, +****This document provides information for developers who want to contribute to the Suyu emulator project, particularly focusing on the GUI aspects. ## Qt GUI in Suyu @@ -81,4 +81,720 @@ This overview provides a solid foundation for understanding Qt's core concepts and how it implements GUIs. You can further expand this section in your documentation by providing more detailed explanations of specific concepts, examples of GUI code, and guidance on choosing the right approach -(Qt Widgets or Qt Quick) for different scenarios. \ No newline at end of file +(Qt Widgets or Qt Quick) for different scenarios. + +## Qt Includes in the Suyu Project + +This section lists all the Qt includes found in the Suyu project, grouped by module. + +### QtCore + +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` + +### QtGui + +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` + +### QtWidgets + +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` + +### QtMultimedia + +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` + +### QtNetwork + +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` + +### QtOpenGL + +* `#include ` +* `#include ` +* `#include ` + +### QtWebEngine + +* `#include ` + +### QtXml + +* `#include ` + +### Others + +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` +* `#include ` + +> This list is based on the code analyzed in the Suyu project. It may not be exhaustive, as other Qt modules +> or headers might be used in different parts of the project. + +> This list is for the Suyu project specifically. Other Qt projects may use different modules and have +> different include dependencies.**** + + +## Files and Classes with Qt Includes in Suyu + +This section lists the files and classes in the Suyu project that include Qt headers, indicating their involvement +in the GUI or other Qt-related functionalities. + + +### Source Files +> [!Warning] The files might be not correct, needs checking +* `src/main.cpp` +* `src/ui/mainwindow.cpp` +* `src/ui/configdialog.cpp` +* `src/ui/aboutdialog.cpp` +* `src/ui/progressdialog.cpp` +* `src/suzu/applets/qt_controller_applet.cpp` +* `src/suzu/util/filesystem.cpp` +* `src/suzu/util/string_util.cpp` +* `src/suzu/core/boot/boot_core.cpp` +* `src/suzu/core/loader/loader_core.cpp` +* `src/suzu/video_core/vk_renderer.cpp` +* `src/suzu/video_core/opengl_renderer.cpp` +* `src/suzu/audio_core/audio_core.cpp` +* `src/suzu/input_core/input_core.cpp` +* `src/suzu/core/core.cpp` +* `src/suzu/configuration/config.cpp` +* `src/suzu/core/file_sys/qt_file_sys.cpp` +* `src/suzu/debugger/debugger.cpp` + +### Classes + +* `MainWindow` +* `ConfigDialog` +* `AboutDialog` +* `ProgressDialog` +* `QtControllerApplet` +* `Config` +* `QtAudioRenderer` +* `QtKeyboard` +* `QtMouse` +* `QtGamepad` +* `QtTouchscreen` +* `QtRenderer` +* `QtFileUtil` +* `Debugger` + +This list highlights the files and classes that directly interact with Qt, giving developers a clearer picture of +where GUI-related code resides and how different parts of the emulator utilize Qt functionalities. + +The Suyu emulator utilizes the Qt framework for its graphical user interface (GUI). This section provides an overview +of how the Qt GUI functions within the project. + +### The `setupUi` Call + +A central element in Qt GUI programming is the `setupUi` function. This function is typically generated by Qt's User +Interface Compiler (`uic`) from UI files (`.ui` files) created in Qt Designer. + +* **UI Files:** +These files define the visual structure of the interface, including widgets, layouts, and connections. +* **Code Generation:** +`uic` translates the XML-based UI files into C++ code, which is then used to create and initialize the GUI elements. +* **`setupUi` Function:** +This generated function takes a pointer to a widget (usually a window or dialog) as an argument and populates +it with the UI elements defined in the UI file. + +In Suyu, you'll likely find calls to `setupUi` in the constructors of dialogs or windows. This is where the GUI +is initialized and displayed to the user. + +### Signal and Slot Mechanism + +Qt uses a signal and slot mechanism for communication between objects. + +* **Signals:** Signals are emitted by objects when certain events occur (e.g., a button click, a window close). +* **Slots:** Slots are functions that are called in response to signals. + +In the UI files, connections are defined between signals and slots. When a signal is emitted, the connected slot +is automatically invoked. This allows you to define the behavior of your GUI in response to user interactions. + +For example, a button's `clicked` signal might be connected to a slot that performs a specific action, such as +starting the emulation or opening a settings dialog. + +### Formatting and Styling + +Qt provides several ways to format and style the GUI: + +* **Qt Style Sheets (QSS):** +Similar to CSS, QSS allows you to apply styles to widgets, changing their appearance (colors, fonts, spacing). +You can define QSS rules in separate files or embed them directly in your code. +* **Layout Managers:** +Qt offers layout managers (`QVBoxLayout`, `QHBoxLayout`, `QGridLayout`) to control the arrangement of widgets +within a window. These managers ensure that the UI adapts to different window sizes and screen resolutions. +* **Custom Widgets:** You can create custom widgets by subclassing existing Qt widgets or creating your +own from scratch. This allows you to extend the functionality and appearance of the UI. + +By understanding the `setupUi` call, the signal and slot mechanism, and the formatting options, you can gain a +solid grasp of how the Qt GUI functions within the Suyu project and how you can modify or extend it. + + +## Implementing Qt Without Qt Designer or Creator + +While Qt Designer and Qt Creator provide convenient tools for visual UI design and development, it's entirely +possible to implement a Qt GUI without relying on these tools. This approach offers greater control and flexibility, +especially for developers who prefer to work directly with code. + +### Creating Widgets Programmatically + +Instead of using Qt Designer to visually design the UI, you can create Qt widgets programmatically using C++ code. +This involves: + +* **Instantiating Widgets:** +Create instances of Qt widget classes (`QPushButton`, `QLabel`, `QLineEdit`, etc.) using their constructors. +* **Setting Properties:** +Set the properties of the widgets, such as their size, position, text, and other attributes. +* **Adding to Layouts:** +Organize the widgets within layouts (`QVBoxLayout`, `QHBoxLayout`, `QGridLayout`) to control their arrangement +and ensure proper resizing behavior. + +### Example {id="example_1"} + +Here's a simple example of creating a window with a button and a label programmatically: + +```c++ +#include +#include +#include +#include + +int main(int argc, char *argv[]) { + QApplication app(argc, argv); + + QWidget window; + window.setWindowTitle("My Window"); + + QPushButton button("Click Me!"); + QLabel label("Hello, world!"); + + QVBoxLayout layout(&window); + layout.addWidget(&button); + layout.addWidget(&label); + + window.show(); + return app.exec(); +} +``` + +This code creates a window with a vertical layout containing a button and a label. + +### Handling Signals and Slots + +Even without Qt Designer's visual connection editor, you can still connect signals and slots +programmatically using the `connect()` function. This allows you to define the behavior of +your GUI in response to user interactions. + +```c++ +// Connect the button's clicked signal to a slot +// that prints a message to the console +QObject::connect(&button, &QPushButton::clicked, + &app, []() { qDebug() << "Button clicked!"; }); +``` + +### Styling with QSS + +You can still style your UI using Qt Style Sheets (QSS) without Qt Creator. Define your QSS rules in a separate file or embed them directly in your code using the `setStyleSheet()` method. + +```c++ +button.setStyleSheet("background-color: blue; color: white;"); +``` + +### Advantages and Disadvantages + +**Advantages:** + +* **Fine-grained Control:** You have complete control over every aspect of the UI. +* **Dynamic UIs:** You can create UIs that change dynamically at runtime based on user actions or data. +* **Code Reusability:** You can create custom widgets and reuse them in different parts of your application. + +**Disadvantages:** + +* **More Code:** You'll need to write more code compared to using Qt Designer. +* **Steeper Learning Curve:** It requires a deeper understanding of Qt's widget classes and layout system. +* **Less Visual:** You don't have the immediate visual feedback that Qt Designer provides. + +Implementing Qt without Qt Designer or Creator can be a powerful approach for developers who prefer a +code-centric workflow and require maximum control over their UI. + +## Styling with Qt Style Sheets (QSS) + +Qt Style Sheets (QSS) provide a powerful mechanism for customizing the appearance of Qt widgets. QSS is +ery similar to CSS (Cascading Style Sheets) used for styling web pages, allowing you to define styles for +various aspects of your GUI, such as colors, fonts, spacing, and borders. + +### Applying Styles + +You can apply QSS styles in several ways: + +* **Inline Styles:** Set the styles directly on a widget using the `setStyleSheet()` method: + + ```c++ + QPushButton *button = new QPushButton("My Button"); + button->setStyleSheet("background-color: red; color: white;"); + ``` + +* **Object-Specific Styles:** Set styles for a specific object type: + + ``` + QPushButton { + background-color: green; + border: 2px solid black; + } + ``` + +* **Application-Wide Styles:** Set styles for the entire application using `QApplication::setStyleSheet()`: + + ```c++ + QApplication app(argc, argv); + app.setStyleSheet("QLineEdit { background-color: yellow; }"); + ``` + +* **External Stylesheets:** Load styles from an external QSS file: + + ```c++ + QFile styleSheetFile("mystyles.qss"); + styleSheetFile.open(QFile::ReadOnly); + QString styleSheet = QLatin1String(styleSheetFile.readAll()); + app.setStyleSheet(styleSheet); + ``` + +### Selectors + +QSS uses selectors to target specific widgets or groups of widgets, similar to CSS. + +* **Type Selector:** Selects widgets by their type (e.g., `QPushButton`, `QLabel`). +* **Class Selector:** Selects widgets by their object name (e.g., `#myButton`). +* **Descendant Selector:** Selects widgets that are descendants of another widget (e.g., `QWidget QPushButton` +selects all `QPushButton` widgets that are children of a `QWidget`). + +### Properties + +QSS provides a wide range of properties to style widgets, including: + +* **Background:** `background-color`, `background-image` +* **Border:** `border`, `border-width`, `border-color`, `border-style` +* **Font:** `font-family`, `font-size`, `font-weight`, `font-style` +* **Color:** `color` (text color) +* **Spacing:** `padding`, `margin` +* **Alignment:** `text-align` + +### Example + +``` +QPushButton { + background-color: #4CAF50; /* Green */ + border: none; + color: white; + padding: 15px 32px; + text-align: center; + font-size: 16px; +} + +QPushButton:hover { + background-color: #3e8e41; /* Darker green */ +} +``` + +This QSS code styles all `QPushButton` widgets with a green background, white text, and a hover effect. + +QSS is a flexible and powerful tool for customizing the look and feel of your Qt GUI. By understanding its +syntax and properties, you can create visually appealing and user-friendly interfaces for your applications. + + +## Creating UI Files from Scratch + +While Qt Designer offers a visual approach to designing user interfaces, you can also create UI files (`.ui`) +manually using a plain text editor. This method provides more control and flexibility, especially when dealing +with complex or dynamic layouts. + +UI files are XML-based documents that describe the structure and properties of your Qt GUI. They define the +widgets, layouts, and connections between them. + +### Basic Structure + +A typical UI file has the following structure: + +```xml + + + MyDialog + + + + 0 + 0 + 400 + 300 + + + + My Dialog + + + + + + Hello, world! + + + + + + + Click Me + + + + + + + + +``` + +* ``: The root element of the UI file. +* ``: Specifies the name of the corresponding C++ class. +* ``: Defines a widget, such as a dialog (`QDialog`), main window (`QMainWindow`), or a basic widget +(`QWidget`). +* ``: Sets properties of the widget (e.g., geometry, window title). +* ``: Defines the layout manager for arranging widgets (e.g., `QVBoxLayout`, `QHBoxLayout`, `QGridLayout`). +* ``: Represents an item within a layout. +* ``: (Optional) For adding resources like images or icons. +* ``: (Optional) For defining signal-slot connections. + +### Creating a UI File + +1. **Choose a Text Editor:** Use a plain text editor or an IDE with XML support (e.g., VS Code, Sublime Text, +Qt Creator). + +2. **Create a New File:** Create a new file with a `.ui` extension (e.g., `mydialog.ui`). + +3. **Add the Basic Structure:** Start with the basic XML structure shown above, replacing `MyDialog` with +the name of your dialog or window class. + +4. **Add Widgets and Layouts:** Add `` elements for the UI components you want to include (buttons, +labels, etc.) and use `` elements to arrange them. + +5. **Set Properties:** Use `` elements to set the properties of the widgets (e.g., size, position, text). + +6. **Define Connections (Optional):** If you want to define signal-slot connections in the UI file, add +`` elements within the `` section. + +7. **Save the File:** Save the file with the `.ui` extension. + +### Using the UI File + +Once you have created the UI file, you can use it in your Qt project: + +* **Qt Creator:** If you're using Qt Creator, you can add the UI file to your project and use it to generate +UI header files. +* **`uic` Compiler:** You can use the `uic` compiler to generate C++ code from the UI file, which you can then +include in your project. + +Creating UI files from scratch gives you fine-grained control over your GUI design and allows you to create +complex and dynamic interfaces. It's a valuable skill for Qt developers who want to go beyond the visual tools +and work directly with the UI definition files. + +## Compiling UI Files with `uic` + +The `uic` (User Interface Compiler) is a command-line tool included with Qt. It processes UI files (`.ui`) +and generates C++ code that represents the user interface, allowing you to integrate your UI design with your +application logic. + +This section explains how to use `uic` without relying on Qt Creator or Qt Designer. + +### Prerequisites + +* **Qt Installation:** Ensure you have Qt installed on your system. The `uic` tool is usually found in the +`bin` directory of your Qt installation. +* **UI File:** Have your UI file (`.ui`) ready, either created in Qt Designer or manually written. + +### Compilation Steps + +1. **Open a Terminal or Command Prompt:** Open a terminal or command prompt and navigate to the directory +where your UI file is located. + +2. **Run `uic`:** Execute the following command to generate both a header (`.h`) and a source (`.cpp`) file: + + ```bash + uic -o \ + -i -o + ``` + + * ``: The name you want for the generated header file (e.g., `mydialog.h`). + * ``: The name of your UI file (e.g., `mydialog.ui`). + * ``: The name you want for the generated source file (e.g., `mydialog.cpp`). + + **Example:** + + ```bash + uic -o mydialog.h mydialog.ui \ + -i mydialog.h -o mydialog.cpp mydialog.ui + ``` + + This command will produce: + + * `mydialog.h`: Contains the class definition for the UI. + * `mydialog.cpp`: Contains the implementation of the `setupUi()` function. + +### Using the Generated Code + +The generated header file will contain a class that inherits from `QWidget` (or a subclass like `QDialog` or +`QMainWindow`) and defines the UI elements and their properties. + +Here's how to use it in your Qt application: + +1. **Include the Header:** Include the generated header file in your C++ code: + + ```c++ + #include "mydialog.h" + ``` + +2. **Create an Instance:** Create an instance of the generated class: + + ```c++ + MyDialog dialog; + ``` + +3. **Call `setupUi()`:** Call the `setupUi()` method on the instance, passing a pointer to the widget +4. where you want to create the UI: + + ```c++ + dialog.setupUi(&dialog); + dialog.show(); + ``` + +By using `uic`, you effectively separate the UI design from your application logic, leading to +more organized and maintainable code. This is particularly useful for manual UI file creation or +when you need more control over code generation. + +## Glossary of Terms + +This glossary defines common terms used throughout the documentation that might be unfamiliar to some readers. + +### A + +* **API (Application Programming Interface):** A set of rules and specifications that allow one application to +access the features or data of another application. +* **AsciiDoc:** A lightweight markup language used for writing documentation. It can be converted to +various output formats like HTML and PDF. +* **Asciidoctor:** A toolchain for processing and converting AsciiDoc documents. + +### B + +* **Backend:** The underlying technology or framework that supports an application or system. In the context +of Qt, the backend could refer to the graphics rendering system (OpenGL, Vulkan) or the windowing system. +* **Branch:** In version control systems like Git, a branch is a separate line of development that allows +you to work on features or bug fixes in isolation. +* **Build System:** A set of tools and processes used to compile and link code into an executable program. +Examples include CMake and qmake. + +### C + +* **CI/CD (Continuous Integration/Continuous Deployment):** A set of practices that automate the building, +testing, and deployment of software. +* **Class:** In object-oriented programming, a class is a blueprint for creating objects. It defines the data +and methods that the objects will have. +* **Commit:** In version control systems, a commit is a snapshot of changes made to files in a repository. +* **Compiler:** A program that translates source code (e.g., C++) into machine code that can be executed by a +computer. +* **CSS (Cascading Style Sheets):** A language used to describe the presentation of HTML documents, +controlling aspects like colors, fonts, and layout. + +### D + +* **Debugger:** A tool that allows developers to step through code, examine variables, and find and fix errors. +* **Dependency:** A software library or component that a program relies on to function correctly. +* **Deployment:** The process of making an application available for use. + +### E + +* **Emulator:** Software that mimics the behavior of a hardware device or system, allowing you to run +software designed for that device on a different platform. +* **Event:** An occurrence or action, such as a mouse click, key press, or window resize, that a +program can respond to. +* **Event Handling:** The process of responding to events in a program. + +### F + +* **Fork:** In version control platforms like GitHub, a fork is a copy of a repository that allows you to +make changes without affecting the original. +* **Framework:** A collection of libraries, tools, and conventions that provide a foundation for developing +software. Qt is a framework for cross-platform application development. +* **Frontend:** The part of an application that users interact with directly, typically the graphical +user interface (GUI). + +### G + +* **Git:** A distributed version control system used to track changes to files and collaborate on +software development. +* **GUI (Graphical User Interface):** A type of user interface that allows users to interact with a +program using visual elements like windows, buttons, and menus. + +### H + +* **Header File:** In C++, a header file (`.h`) contains declarations of classes, functions, and variables. +* **HTML (HyperText Markup Language):** The standard markup language for creating web pages. + +### I + +* **IDE (Integrated Development Environment):** A software application that provides tools for writing, +editing, debugging, and building code. Qt Creator is an IDE for Qt development. +* **Include Directive:** In C++, the `#include` directive is used to include header files in a source file. + +### L + +* **Layout Manager:** In Qt, a layout manager is used to arrange widgets within a window or container. +Examples include `QVBoxLayout`, `QHBoxLayout`, and `QGridLayout`. +* **Library:** A collection of pre-compiled code that can be used by other programs. Qt is a collection +of libraries for cross-platform development. + +### M + +* **Markup Language:** A system for annotating text with tags that indicate formatting or structure. +Examples include HTML, XML, and AsciiDoc. +* **Merge:** In version control systems, merging combines changes from different branches into a +single branch. +* **Module:** A self-contained unit of code that provides specific functionality. Qt is organized +into modules like `QtCore`, `QtGui`, and `QtWidgets`. + +### O + +* **Object:** In object-oriented programming, an object is an instance of a class. It has its own +data and can perform actions defined by its class. +* **Open Source:** Software whose source code is freely available and can be modified and redistributed. + +### P + +* **Pull:** In Git, pulling fetches changes from a remote repository and merges them into your local branch. +* **Push:** In Git, pushing sends your local commits to a remote repository. + +### Q + +* **QML (Qt Modeling Language):** A declarative language used to describe user interfaces in Qt Quick. +* **QSS (Qt Style Sheets):** A language similar to CSS used to style Qt widgets. +* **Qt:** A cross-platform framework for developing applications with graphical user interfaces. +* **Qt Creator:** An IDE for Qt development. +* **Qt Designer:** A visual tool for designing Qt user interfaces. + +### R + +* **Repository:** In version control systems, a repository is a central location where code and its +history are stored. +* **Runtime:** The period when a program is executing. + +### S + +* **Signal:** In Qt, a signal is a notification that an object emits when a particular event occurs. +* **Slot:** In Qt, a slot is a function that can be connected to a signal to be executed when the +signal is emitted. +* **Source Code:** The human-readable code written by developers. + +### U + +* **UI (User Interface):** The means by which a user interacts with a program. +* **UI File:** In Qt, a UI file (`.ui`) is an XML-based file that describes the structure and +properties of a user interface. +* **`uic` (User Interface Compiler):** A Qt tool that processes UI files and generates C++ code. + +### V + +* **Version Control:** A system for tracking changes to files over time. +* **Virtual Machine:** Software that emulates a computer system. + +### W + +* **Widget:** In Qt, a widget is a visual element in a user interface, such as a button, label, or text box. \ No newline at end of file