Merge pull request #15 from EasyScience/examples

Add 3 types of the most basic examples with an additional backend proxy layer and a new way to globally access QML components

.github/workflows/wasm.yml

@@ -0,0 +1,106 @@
+name: wasm
+
+on:
+  push:
+  #schedule:
+  #  - cron: '*/120 8-18 * * *'  # every 2 hours from 8:00 to 18:00 every day
+
+jobs:
+  wasm-build: # the first job
+    # current job matrix. if modified, remember to UPDATE the strategy in the next job
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-14]
+
+    runs-on: ${{ matrix.os }}
+
+    timeout-minutes: 30
+
+    steps: # job steps
+      - name: Check-out repository
+        uses: actions/checkout@v4
+
+      - name: Cache emsdk
+        id: cache-emsdk
+        uses: actions/cache@v4
+        with:
+          path: ${{ github.workspace }}/emsdk
+          key: ${{ runner.os }}-emsdk
+
+      - name: Install emsdk
+        if: steps.cache-emsdk.outputs.cache-hit != 'true'
+        shell: bash
+        run: |
+          git clone https://github.com/emscripten-core/emsdk.git
+          cd emsdk
+          git pull
+          ./emsdk install 3.1.50		# this version is needed for Qt 6.7
+          ./emsdk activate 3.1.50
+
+      - name: Cache Qt
+        id: cache-qt
+        uses: actions/cache@v4
+        with:
+          path: ${{ github.workspace }}/Qt
+          key: ${{ runner.os }}-qt
+
+      - name: Install Qt for WebAssembly
+        if: steps.cache-qt.outputs.cache-hit != 'true'
+        shell: bash
+        run: |
+          curl -L -O https://download.qt.io/official_releases/online_installers/qt-unified-mac-x64-online.dmg
+          chmod u+x qt-unified-mac-x64-online.dmg
+          hdiutil attach qt-unified-mac-x64-online.dmg
+          /Volumes/qt-online-installer-macOS-x64-4.8.0/qt-online-installer-macOS-x64-4.8.0.app/Contents/MacOS/qt-online-installer-macOS-x64-4.8.0 \
+          --email ${{ secrets.QT_ACCOUNT_EMAIL }} \
+          --pw ${{ secrets.QT_ACCOUNT_PASSWORD }} \
+          --root ${{ github.workspace }}/Qt \
+          --accept-licenses \
+          --accept-obligations \
+          --default-answer \
+          --confirm-command \
+          install qt.qt6.672.wasm_singlethread qt.qt6.672.qt5compat
+          hdiutil detach /Volumes/qt-online-installer-macOS-x64-4.8.0
+
+      - name: Print some debug info
+        shell: bash
+        run: |
+          source ${{ github.workspace }}/emsdk/emsdk_env.sh
+          em++ --version
+          export PATH=$PATH:${{ github.workspace }}/Qt/6.7.2/wasm_singlethread/bin
+          qmake -v
+
+      - name: Build WASM from BasicC++ example
+        shell: bash
+        run: |
+          source ${{ github.workspace }}/emsdk/emsdk_env.sh
+          export PATH=$PATH:${{ github.workspace }}/Qt/6.7.2/wasm_singlethread/bin
+          cd examples/BasicC++/src
+          qmake BasicC++.pro -spec wasm-emscripten
+          make -j
+
+      - name: Copy the built WASM to the build/wasm folder
+        shell: bash
+        run: |
+          mkdir -p build/wasm
+          cp examples/BasicC++/src/*.wasm build/wasm
+          cp examples/BasicC++/src/*.html build/wasm
+          cp examples/BasicC++/src/*.js build/wasm
+          cp examples/BasicC++/src/*.svg build/wasm
+
+      - name: Upload the zipped wasm folder
+        uses: actions/upload-artifact@v4
+        with:
+          name: wasm  # name of the zip file to be created and uploaded
+          path: build/wasm  # directory whose content is to be zipped
+          compression-level: 0  # no compression
+          if-no-files-found: error
+
+      - name: Push the built wasm to the webapp branch
+        uses: s0/git-publish-subdir-action@develop
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_API_PERSONAL_ACESS_TOKEN }}
+          REPO: self
+          BRANCH: webapp
+          FOLDER: build/wasm  # directory whose content is to be pushed

.gitignore

@@ -1,17 +1,27 @@
-# QtCreator
+# Qt Creator
 *.autosave
 
-# QtCreator Qml
+# Qt Creator Qml
 *.qmlproject.user
 *.qmlproject.user.*
 
-# QtCreator Python
+# Qt Creator Python
 *.pyproject.user
 *.pyproject.user.*
 
-# QtCreator CMake
+# Qt Creator C++
+*.pro.user
+*.pro.user.*
+
+# Qt Creator CMake
 CMakeLists.txt.user*
 
+# VS Code
+.vscode/
+
+# PyCharm
+.idea/
+
 # Fortran
 fort.1
 
@@ -44,4 +54,3 @@ build
 settings.ini*
 temp.cif
 .ci/
-.idea/

.vscode/launch.json

@@ -0,0 +1,39 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python Debugger: Current File",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "env": {
+                "PYTHONPATH": "${cwd}/src"
+                }
+        },
+        {
+            "name": "Python Debugger: BasicPy",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${cwd}/examples/BasicPy/src/BasicPy/main.py",
+            "console": "integratedTerminal",
+        },
+        {
+            "name": "Python Debugger: IntermediatePy",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${cwd}/examples/IntermediatePy/src/IntermediatePy/main.py",
+            "console": "integratedTerminal",
+        },
+        {
+            "name": "Python Debugger: AdvancedPy",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${cwd}/examples/AdvancedPy/src/AdvancedPy/main.py",
+            "console": "integratedTerminal",
+        }
+    ]
+}

EXAMPLES.md

@@ -0,0 +1,139 @@
+## Types of examples
+
+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 |
+| 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 
+
+### Python environment
+
+* Create and activate a python environment (_optional_)
+
+  ***macOS and Linux***
+
+  ```
+  python3.11 -m venv .venv
+  source .venv/bin/activate
+  ```
+
+  ***Windows***
+
+  ```
+  python3.11 -m venv .venv
+  .venv\Scripts\activate
+  ```
+
+* Upgrade PIP, the package installer for Python (_optional_)
+
+  ```
+  pip install --upgrade pip
+  ```
+
+* Install the Qt for Python `PySide6` package using PIP
+
+  ```
+  pip install --force-reinstall "PySide6>=6.6,<6.7" 
+  ```
+
+### Integrated development environment (IDE)
+
+#### 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
+	   * [ ] Qt 6.7.z
+	       * [x] Desktop (***macOS***) or MSVC 2019 64-bit (***Windows***)
+	       * [x] Qt 5 Compatibility Module
+	       * [x] Qt Shader Tools
+   	       * [ ] Additional Libraries
+   	           * [x] Qt Charts  
+	   * [ ] Developer and Designer Tools
+	       * [x] Qt Creator x.y.z
+
+#### 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
+* The initial launch configuration is in the `.vscode/launch.json` file, which should be automatically 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)
+
+This example is located in `examples/BasicQml` and the source code is in the subfolder `src/BasicQml`. The example consists of a graphical QML frontend (`Gui/Application.qml`) and a QML backend (`Logic/Mock/BackendProxy.qml`). It is considered a mock backend as it only returns hardcoded values rather than providing the required functionality. The entry point for Qt is `main.qml`, which can be displayed using Qt `qml` viewer.
+
+#### Run using the QML Runtime
+
+##### Run via the Qt Creator IDE
+
+* Run Qt Creator
+* Open the qml project file from the example folder `examples/BasicQml/src/BasicQml.qmlproject`
+* Click Run (Green play button)
+
+#### How to edit GUI elements in live mode
+
+* In Qt Creator, select the `*.qml` file to be edited in live mode
+* Click the `Design` button at the top of the left sidebar of `Qt Creator`
+    * _Note: If this button is disabled, find and click `About plugins...` in the `Qt Creator` menu, scroll down to the `Qt Quick` section and enable `QmlDesigner`._
+* In the `Design` window, click the `Show Live Preview` button in the top panel of the application (small play button in a circle).
+    * _Note: Showing the entire `main.qml` application window in live mode works best when the open `main.qml` is moved to another monitor and does not overlap with the `Qt Creator` window_.
+* When the desired GUI component appears, you can click the `Edit` button at the top of the left sidebar of `Qt Creator` to return to the source code of that qml component and still see it live in a separate window.
+
+### Type II Examples: BasicPy (Python runtime with QML backend)
+
+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
+
+##### Run from the terminal
+
+* Go to the example folder, e.g.,
+
+  ```sh
+  $ cd examples/BasicPy/src/BasicPy
+  ```
+* Run using Python (provided that the required python environment is activated as explained above)
+
+  ```sh
+  $ python main.py
+  ```
+
+##### 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_)
+
+* 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 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++ (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.
+
+This example is currently used to create a WebAssembly application that can be run inside a web browser.

LICENSE.md → LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2021-2022, European Spallation Source
+Copyright (c) 2024, EasyApp contributors (https://github.com/easyscience/EasyApp).
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

README.md

@@ -0,0 +1,23 @@
+<img src="https://github.com/EasyScience/EasyApp/blob/examples/resources/images/ea_logo.svg?raw=true" height="65">
+
+EasyApp is a collection of Qt QML graphical components which allows one to quickly create cross-platform applications with an eye-catching and intuitive graphical interface based on the [EasyScience](http://github.com/EasyScience) framework.
+
+* Website: https://app.easyscience.software
+* Source code: https://github.com/EasyScience/EasyApp
+* Bug reports: https://github.com/EasyScience/EasyApp/issues
+
+EasyApp is currently being used as the basis for the graphical interface in the following projects:
+
+* [EasyDiffraction](http://github.com/EasyScience/EasyDiffraction)
+* [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](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](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++](https://github.com/EasyScience/EasyApp/tree/master/examples/BasicC++) example at https://easyscience.github.io/EasyApp/BasicC++.html.