Update readme [ci skip]

easyscience · Sep 2, 2024 · 408b38d · 408b38d
1 parent 717e15f
commit 408b38d
Show file tree

Hide file tree

Showing 3 changed files with 42 additions and 53 deletions.
diff --git a/EXAMPLES.md b/EXAMPLES.md
@@ -1,15 +1,14 @@
 ## Types of examples
 
-Different types of examples are provided. All examples have a graphical frontend implemented in QML, but differ in the way the backend logic is implemented and the runtime used to run them. These examples can be categorised as shown in the following table:
+Different types of examples are given here. All examples have a graphical frontend implemented in QML, but differ in the way the backend logic is implemented and the runtime used to run them. These examples can be categorised as shown in the following table:
 
 | Example        | Type | Frontend | Backend  | Runtime              |
 | -------------- | ---- | -------- | -------- | -------------------- |
 | BasicQml       | I    | QML      | Mock QML | `qml` tool           |
 | BasicPy        | II   | QML      | Mock QML | `python` interpreter |
-| BasicC++       | IV   | QML      | Mock QML | need to be compiled  |
 | IntermediatePy | III  | QML      | Python   | `python` interpreter |
 | AdvancedPy     | III  | QML      | Python   | `python` interpreter |
-
+| BasicC++       | IV   | QML      | Mock QML | need to be compiled  |
 
 ## Setting up Python and IDE 
 
@@ -31,13 +30,13 @@ Different types of examples are provided. All examples have a graphical frontend
   .venv\Scripts\activate
   ```
 
-* Upgrade the PIP - package installer for Python (_optional_)
+* Upgrade PIP, the package installer for Python (_optional_)
 
   ```
   pip install --upgrade pip
   ```
 
-* Install the Qt for Python `PySide6` package via PIP
+* Install the Qt for Python `PySide6` package using PIP
 
   ```
   pip install --force-reinstall "PySide6>=6.6,<6.7" 
@@ -47,6 +46,8 @@ Different types of examples are provided. All examples have a graphical frontend
 
 #### Qt Creator
 
+Qt Creator is a prefered IDE for developing the GUI in QML. It allows to run QML code in debug mode with breakpoints, preview changes to QML code in live mode, has build in documentation for QML modules, has QML code auto-completion, and more unique feature related to the QML code.
+
 * Download Qt Online Installer from [qt.io](https://www.qt.io/download-qt-installer-oss). More info at [doc.qt.io](https://doc.qt.io/qt-6/qt-online-installation.html).
 * Install Qt for desktop development using a custom installation that includes the following components:
     * Qt
@@ -61,12 +62,13 @@ Different types of examples are provided. All examples have a graphical frontend
 
 #### VS Code (_alternative to Qt Creator_)
 
+VS Code is an alternative IDE to Qt Creator. It has a syntax highlighting plugin for QML code, but lacks some of the unique features of Qt Creator mentioned above to make QML development easier.
+
 * Download an install VS Code
 * Add the python extension
 * Rename the folder `vscode` to `.vscode`. The `launch.json` file will then be read by VS Code
 * Select any python file in the repo and choose the desired python environment
 
-
 ## How to run
 
 ### Type I Examples: BasicQml (QML runtime with QML backend)
@@ -75,21 +77,7 @@ This example is located in `examples/BasicQml` and the source code is in the sub
 
 #### Run using the QML Runtime
 
-##### Run from the terminal
-
-* Go to the example folder, e.g.,
-
-  ```sh
-  cd examples/BasicQml/src/BasicQml
-  ```
-
-* Run `main.qml` (specifying the paths to the current directory `.` and the EasyApp module directory `../../../..`) using the `qml` tool installed with the Qt Framework in the previous step, e.g., like this
-
-  ```sh
-  ~/Qt/6.x.y/macos/bin/qml -I . -I ../../../.. main.qml
-  ```
-
-##### Run via the Qt Creator IDE (_alternative to run from the terminal_)
+##### Run via the Qt Creator IDE
 
 * Run Qt Creator
 * Open the qml project file from the example folder `examples/BasicQml/src/BasicQml.qmlproject`
@@ -106,7 +94,7 @@ This example is located in `examples/BasicQml` and the source code is in the sub
 
 ### Type II Examples: BasicPy (Python runtime with QML backend)
 
-This example is located in `examples/BasicPy` with the source code in `src/BasicPy`. This example serves to demonstrate how an application with a QML frontend and a QML backend (similar to the Type I example) can be executed from Python. The entry point for the Python program is `main.py` file. To execute this do the following:
+This example is in the `examples/BasicPy` folder, and the source code is in the `examples/BasicPy/src/BasicPy` folder. This example serves to demonstrate how an application with a QML frontend and QML backend (similar to the Type I example) can be run from Python. The entry point for the Python application is the `main.py` file. To run it, follow the steps below:
 
 #### Run using the Python interpreter
 
@@ -123,28 +111,28 @@ This example is located in `examples/BasicPy` with the source code in `src/Basic
   $ python main.py
   ```
 
-#### Run via the Qt Creator IDE (_alternative to run from the terminal_)
+##### Run via the Qt Creator IDE (_alternative to run from the terminal_)
 
 * Run Qt Creator
 * Open the python project file from the example folder `examples/BasicPy/src/BasicPy.pyproject`
 * Select the desired python environment with the Qt `PySide6` module installed
 * Click Run (Green play button)
 
-#### Run via the VS Code IDE (_alternative to run from the terminal or via the Qt Creator IDE_)
+##### Run via the VS Code IDE (_alternative to run from the terminal or via the Qt Creator IDE_)
 
 * Open the repo in VS Code
 * Click on the debug extension and select which example to execute
 ![Debug dropdown window](resources/images/vscode_debug.jpg)
 
 ### Type III Examples: IntermediatePy and AdvancedPy (Python runtime with Python backend)
 
-These examples demonstrate how to use a Python runtime to execute the QML frontend and the Python backend located in `Backends/real_backend.py`. These examples can be run through Python in the same way as Type II described above. These examples have a Python-based backend (proxy object), which gets created in `main.py` and then exposed to QML. The Qt QML GUI then acceses the backend by calling methods exposed by the proxy object in the `Backends/real_py` folder.
+These examples demonstrate how to use the Python runtime to run the QML GUI binded with the Python backend located in `Backends/real_backend.py`. These examples can be run through Python in the same way as Type II described above. In these examples, the Python-based backend is registered in `main.py` and then imported into QML. The Qt QML GUI then accesses the backend by calling the properties and methods of the classes defined in the `Backends/real_py` folder.
 
 #### Possible Issues
 
 * If in Qt Creator some components are highlighted and marked as "Unknown component. (M300)", try resetting via "Tools > QML/JS > Reset Code Model".
 
-### Type IV Examples: BasicC++
+### Type IV Examples: BasicC++ (QML backend)
 
 This example can be run after compilation into an executable program. It only has a mock backend in QML (the C++ backend is not implemented). The minimum configuration requires a base `main.cpp` file and, if Qt Creator is used as the IDE, a `*.pro` file.
 

diff --git a/README.md b/README.md
@@ -12,12 +12,12 @@ EasyApp is currently being used as the basis for the graphical interface in the
 * [EasyReflectometry](http://github.com/EasyScience/EasyReflectometry)
 * [EasyTexture](http://github.com/EasyScience/EasyTextureApp)
 
-More simple examples of how to use EasyApp are described in [EXAMPLES.md](EXAMPLES.md) and presented in the [examples](examples) directory:
+More simple examples of how to use EasyApp are described in [EXAMPLES.md](https://github.com/EasyScience/EasyApp/blob/master/EXAMPLES.md) and presented in the project [examples](https://github.com/EasyScience/EasyApp/tree/master/examples) directory:
 
-* [BasicQml](examples/BasicQml)
-* [BasicPy](examples/BasicPy)
-* [BasicC++](examples/BasicC++)
-* [IntermediatePy](examples/IntermediatePy)
-* [AdvancedPy](examples/AdvancedPy)
+* [BasicQml](https://github.com/EasyScience/EasyApp/tree/master/examples/BasicQml)
+* [BasicPy](https://github.com/EasyScience/EasyApp/tree/master/examples/BasicPy)
+* [BasicC++](https://github.com/EasyScience/EasyApp/tree/master/examples/BasicC++)
+* [IntermediatePy](https://github.com/EasyScience/EasyApp/tree/master/examples/IntermediatePy)
+* [AdvancedPy](https://github.com/EasyScience/EasyApp/tree/master/examples/AdvancedPy)
 
-If you want to see what EasyApp looks like, you can try the web demo based on the [BasicC++](examples/BasicC++) example at https://easyscience.github.io/EasyApp/BasicC++.html.
+If you want to see what EasyApp looks like, you can try the web demo based on the [BasicC++](https://github.com/EasyScience/EasyApp/tree/master/examples/BasicC++) example at https://easyscience.github.io/EasyApp/BasicC++.html.
diff --git a/examples/AdvancedPy/README.md b/examples/AdvancedPy/README.md
@@ -4,34 +4,35 @@
 
 ```sh
 🗂️ AdvancedPy                               # Current example
-├── LICENSE
+├── LICENSE                                 # Project license file
 ├── pyproject.toml                          # Configuration file used to build the Python package
 ├── README.md                               # Current file that introduces and explains a project
 │
 └── 🗂️ src                                  # Source code
     ├── AdvancedPy.qmlproject               # QML project for the Qt Creator IDE
     ├── AdvancedPy.pyproject                # Python project for the Qt Creator IDE
     │
-    └── 🗂️ AdvancedPy                        # Directory with the name of the current Python package
+    └── 🗂️ AdvancedPy                       # Directory with the name of the current Python package
         ├── __init__.py                     # Executed when the current Python package is imported       
         ├── main.qml                        # Root QML component        
         ├── main.py                         # Root Python file      
         │
         ├── 🗂️ Backends                     # Backend logic
         │   ├── MockBackend.qml             # Parent object for all other objects with mock QML logic
-        │   ├── real_backend.py             # Parent object for all other objects with real python logic
-        │   │
         │   ├── 🗂️ MockQml                  # Mock QML backend to be used if no python backend is defined
         │   │   ├── qmldir                  
         │   │   ├── Status.qml              # Mock logic for the status bar
         │   │   ├── Project.qml             # Mock logic for the application page 'Project'
         │   │   └── Report.qml              # Mock logic for the application page 'Report'
         │   │
+        │   ├── real_backend.py             # Parent object for all other objects with real python logic
         │   └── 🗂️ real_py                  # Real Python backend
-        │       ├── helpers.py              # Some helper functions
         │       ├── status.py               # Logic for the status bar
         │       ├── project.py              # Logic for the application page 'Project'
-        │       └── report.py               # Logic for the application page 'Report'
+        │       ├── report.py               # Logic for the application page 'Report'
+        │       │
+        │       └── 🗂️ logic                # Pure Python logic (not QObject-based)
+        │           └── helpers.py          # Some helper functions
         │
         └── 🗂️ Gui                          # Frontend GUI components
             ├── qmldir                      
@@ -60,21 +61,21 @@
 ```sh
 🗂️ Pages
 │
-├── 🗂️ Home                         # Components of the application 'Home' page
+├── 🗂️ Home                                 # Components of the application 'Home' page
 │   ├── Content.qml
 │   │
 │   └── 🗂️ Popups                   
 │       └── About.qml
 │
-├── 🗂️ Project                      # Components of the application 'Project' page
-│   ├── Layout.qml                  # Layout of the whole page
+├── 🗂️ Project                              # Components of the application 'Project' page
+│   ├── Layout.qml                          # Layout of the whole page
 │   │
-│   ├── 🗂️ MainArea                 # Tabs of the main area
+│   ├── 🗂️ MainArea                         # Tabs of the main area
 │   │   └── Description.qml
 │   │
-│   └── 🗂️ Sidebar                  # Tabs of the sidebar
+│   └── 🗂️ Sidebar                          # Tabs of the sidebar
 │       │
-│       ├── 🗂️ Basic                # Components of the sidebar tab with basic controls
+│       ├── 🗂️ Basic                        # Components of the sidebar tab with basic controls
 │       │   ├── Layout.qml        
 │       │   │
 │       │   ├── 🗂️ Groups           
@@ -86,30 +87,30 @@
 │       │       ├── OpenCifFile.qml
 │       │       └── ProjectDescription.qml
 │       │
-│       ├── 🗂️ Extra                # Components of the sidebar tab with extra controls
+│       ├── 🗂️ Extra                         # Components of the sidebar tab with extra controls
 │       │   ├── Layout.qml        
 │       │   │
 │       │   └── 🗂️ Groups           
 │       │       └── Scrolling.qml
 │       │
-│       └── 🗂️ Text                 # Components of the sidebar tab with text mode controls
+│       └── 🗂️ Text                          # Components of the sidebar tab with text mode controls
 │           └── Layout.qml          
 │
-└── 🗂️ Report                       # Components of the application 'Report' page
-    ├── Layout.qml                  # Layout of the whole page
+└── 🗂️ Report                                # Components of the application 'Report' page
+    ├── Layout.qml                           # Layout of the whole page
     │
-    ├── 🗂️ MainArea                 # Tabs of the main area
+    ├── 🗂️ MainArea                          # Tabs of the main area
     │   └── Summary.qml
     │
-    └── 🗂️ Sidebar                  # Tabs of the sidebar
+    └── 🗂️ Sidebar                           # Tabs of the sidebar
         │
-        ├── 🗂️ Basic                # Components of the sidebar tab with basic controls
+        ├── 🗂️ Basic                         # Components of the sidebar tab with basic controls
         │   ├── Layout.qml   
         │   │       
         │   └── 🗂️ Groups           
         │       └── Export.qml
         │
-        └── 🗂️ Extra                # Components of the sidebar tab with extra controls
+        └── 🗂️ Extra                         # Components of the sidebar tab with extra controls
             ├── Layout.qml          
             │
             └── 🗂️ Groups