Skip to content

Commit 09d08fb

Browse files
AndrewSazonovAndrewSazonov
authored
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
2 parents e95787a + 8b496f7 commit 09d08fb

File tree

430 files changed

+9775
-120
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

430 files changed

+9775
-120
lines changed

‎.github/workflows/wasm.yml

+106
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
name: wasm
2+
3+
on:
4+
push:
5+
#schedule:
6+
# - cron: '*/120 8-18 * * *' # every 2 hours from 8:00 to 18:00 every day
7+
8+
jobs:
9+
wasm-build: # the first job
10+
# current job matrix. if modified, remember to UPDATE the strategy in the next job
11+
strategy:
12+
fail-fast: false
13+
matrix:
14+
os: [macos-14]
15+
16+
runs-on: ${{ matrix.os }}
17+
18+
timeout-minutes: 30
19+
20+
steps: # job steps
21+
- name: Check-out repository
22+
uses: actions/checkout@v4
23+
24+
- name: Cache emsdk
25+
id: cache-emsdk
26+
uses: actions/cache@v4
27+
with:
28+
path: ${{ github.workspace }}/emsdk
29+
key: ${{ runner.os }}-emsdk
30+
31+
- name: Install emsdk
32+
if: steps.cache-emsdk.outputs.cache-hit != 'true'
33+
shell: bash
34+
run: |
35+
git clone https://github.com/emscripten-core/emsdk.git
36+
cd emsdk
37+
git pull
38+
./emsdk install 3.1.50 # this version is needed for Qt 6.7
39+
./emsdk activate 3.1.50
40+
41+
- name: Cache Qt
42+
id: cache-qt
43+
uses: actions/cache@v4
44+
with:
45+
path: ${{ github.workspace }}/Qt
46+
key: ${{ runner.os }}-qt
47+
48+
- name: Install Qt for WebAssembly
49+
if: steps.cache-qt.outputs.cache-hit != 'true'
50+
shell: bash
51+
run: |
52+
curl -L -O https://download.qt.io/official_releases/online_installers/qt-unified-mac-x64-online.dmg
53+
chmod u+x qt-unified-mac-x64-online.dmg
54+
hdiutil attach qt-unified-mac-x64-online.dmg
55+
/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 \
56+
--email ${{ secrets.QT_ACCOUNT_EMAIL }} \
57+
--pw ${{ secrets.QT_ACCOUNT_PASSWORD }} \
58+
--root ${{ github.workspace }}/Qt \
59+
--accept-licenses \
60+
--accept-obligations \
61+
--default-answer \
62+
--confirm-command \
63+
install qt.qt6.672.wasm_singlethread qt.qt6.672.qt5compat
64+
hdiutil detach /Volumes/qt-online-installer-macOS-x64-4.8.0
65+
66+
- name: Print some debug info
67+
shell: bash
68+
run: |
69+
source ${{ github.workspace }}/emsdk/emsdk_env.sh
70+
em++ --version
71+
export PATH=$PATH:${{ github.workspace }}/Qt/6.7.2/wasm_singlethread/bin
72+
qmake -v
73+
74+
- name: Build WASM from BasicC++ example
75+
shell: bash
76+
run: |
77+
source ${{ github.workspace }}/emsdk/emsdk_env.sh
78+
export PATH=$PATH:${{ github.workspace }}/Qt/6.7.2/wasm_singlethread/bin
79+
cd examples/BasicC++/src
80+
qmake BasicC++.pro -spec wasm-emscripten
81+
make -j
82+
83+
- name: Copy the built WASM to the build/wasm folder
84+
shell: bash
85+
run: |
86+
mkdir -p build/wasm
87+
cp examples/BasicC++/src/*.wasm build/wasm
88+
cp examples/BasicC++/src/*.html build/wasm
89+
cp examples/BasicC++/src/*.js build/wasm
90+
cp examples/BasicC++/src/*.svg build/wasm
91+
92+
- name: Upload the zipped wasm folder
93+
uses: actions/upload-artifact@v4
94+
with:
95+
name: wasm # name of the zip file to be created and uploaded
96+
path: build/wasm # directory whose content is to be zipped
97+
compression-level: 0 # no compression
98+
if-no-files-found: error
99+
100+
- name: Push the built wasm to the webapp branch
101+
uses: s0/git-publish-subdir-action@develop
102+
env:
103+
GITHUB_TOKEN: ${{ secrets.GH_API_PERSONAL_ACESS_TOKEN }}
104+
REPO: self
105+
BRANCH: webapp
106+
FOLDER: build/wasm # directory whose content is to be pushed

‎.gitignore

+14-5
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,27 @@
1-
# QtCreator
1+
# Qt Creator
22
*.autosave
33

4-
# QtCreator Qml
4+
# Qt Creator Qml
55
*.qmlproject.user
66
*.qmlproject.user.*
77

8-
# QtCreator Python
8+
# Qt Creator Python
99
*.pyproject.user
1010
*.pyproject.user.*
1111

12-
# QtCreator CMake
12+
# Qt Creator C++
13+
*.pro.user
14+
*.pro.user.*
15+
16+
# Qt Creator CMake
1317
CMakeLists.txt.user*
1418

19+
# VS Code
20+
.vscode/
21+
22+
# PyCharm
23+
.idea/
24+
1525
# Fortran
1626
fort.1
1727

@@ -44,4 +54,3 @@ build
4454
settings.ini*
4555
temp.cif
4656
.ci/
47-
.idea/

‎.vscode/launch.json

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
{
2+
// Use IntelliSense to learn about possible attributes.
3+
// Hover to view descriptions of existing attributes.
4+
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
5+
"version": "0.2.0",
6+
"configurations": [
7+
{
8+
"name": "Python Debugger: Current File",
9+
"type": "debugpy",
10+
"request": "launch",
11+
"program": "${file}",
12+
"console": "integratedTerminal",
13+
"env": {
14+
"PYTHONPATH": "${cwd}/src"
15+
}
16+
},
17+
{
18+
"name": "Python Debugger: BasicPy",
19+
"type": "debugpy",
20+
"request": "launch",
21+
"program": "${cwd}/examples/BasicPy/src/BasicPy/main.py",
22+
"console": "integratedTerminal",
23+
},
24+
{
25+
"name": "Python Debugger: IntermediatePy",
26+
"type": "debugpy",
27+
"request": "launch",
28+
"program": "${cwd}/examples/IntermediatePy/src/IntermediatePy/main.py",
29+
"console": "integratedTerminal",
30+
},
31+
{
32+
"name": "Python Debugger: AdvancedPy",
33+
"type": "debugpy",
34+
"request": "launch",
35+
"program": "${cwd}/examples/AdvancedPy/src/AdvancedPy/main.py",
36+
"console": "integratedTerminal",
37+
}
38+
]
39+
}

‎CHANGELOG.md

-1
This file was deleted.

‎CONTRIBUTING.md

-1
This file was deleted.

‎EXAMPLES.md

+139
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
## Types of examples
2+
3+
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:
4+
5+
| Example | Type | Frontend | Backend | Runtime |
6+
| -------------- | ---- | -------- | -------- | -------------------- |
7+
| BasicQml | I | QML | Mock QML | `qml` tool |
8+
| BasicPy | II | QML | Mock QML | `python` interpreter |
9+
| IntermediatePy | III | QML | Python | `python` interpreter |
10+
| AdvancedPy | III | QML | Python | `python` interpreter |
11+
| BasicC++ | IV | QML | Mock QML | need to be compiled |
12+
13+
## Setting up Python and IDE
14+
15+
### Python environment
16+
17+
* Create and activate a python environment (_optional_)
18+
19+
***macOS and Linux***
20+
21+
```
22+
python3.11 -m venv .venv
23+
source .venv/bin/activate
24+
```
25+
26+
***Windows***
27+
28+
```
29+
python3.11 -m venv .venv
30+
.venv\Scripts\activate
31+
```
32+
33+
* Upgrade PIP, the package installer for Python (_optional_)
34+
35+
```
36+
pip install --upgrade pip
37+
```
38+
39+
* Install the Qt for Python `PySide6` package using PIP
40+
41+
```
42+
pip install --force-reinstall "PySide6>=6.6,<6.7"
43+
```
44+
45+
### Integrated development environment (IDE)
46+
47+
#### Qt Creator
48+
49+
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.
50+
51+
* 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).
52+
* Install Qt for desktop development using a custom installation that includes the following components:
53+
* Qt
54+
* [ ] Qt 6.7.z
55+
* [x] Desktop (***macOS***) or MSVC 2019 64-bit (***Windows***)
56+
* [x] Qt 5 Compatibility Module
57+
* [x] Qt Shader Tools
58+
* [ ] Additional Libraries
59+
* [x] Qt Charts
60+
* [ ] Developer and Designer Tools
61+
* [x] Qt Creator x.y.z
62+
63+
#### VS Code (_alternative to Qt Creator_)
64+
65+
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.
66+
67+
* Download an install VS Code
68+
* Add the python extension
69+
* The initial launch configuration is in the `.vscode/launch.json` file, which should be automatically read by VS Code
70+
* Select any python file in the repo and choose the desired python environment
71+
72+
## How to run
73+
74+
### Type I Examples: BasicQml (QML runtime with QML backend)
75+
76+
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.
77+
78+
#### Run using the QML Runtime
79+
80+
##### Run via the Qt Creator IDE
81+
82+
* Run Qt Creator
83+
* Open the qml project file from the example folder `examples/BasicQml/src/BasicQml.qmlproject`
84+
* Click Run (Green play button)
85+
86+
#### How to edit GUI elements in live mode
87+
88+
* In Qt Creator, select the `*.qml` file to be edited in live mode
89+
* Click the `Design` button at the top of the left sidebar of `Qt Creator`
90+
* _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`._
91+
* In the `Design` window, click the `Show Live Preview` button in the top panel of the application (small play button in a circle).
92+
* _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_.
93+
* 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.
94+
95+
### Type II Examples: BasicPy (Python runtime with QML backend)
96+
97+
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:
98+
99+
#### Run using the Python interpreter
100+
101+
##### Run from the terminal
102+
103+
* Go to the example folder, e.g.,
104+
105+
```sh
106+
$ cd examples/BasicPy/src/BasicPy
107+
```
108+
* Run using Python (provided that the required python environment is activated as explained above)
109+
110+
```sh
111+
$ python main.py
112+
```
113+
114+
##### Run via the Qt Creator IDE (_alternative to run from the terminal_)
115+
116+
* Run Qt Creator
117+
* Open the python project file from the example folder `examples/BasicPy/src/BasicPy.pyproject`
118+
* Select the desired python environment with the Qt `PySide6` module installed
119+
* Click Run (Green play button)
120+
121+
##### Run via the VS Code IDE (_alternative to run from the terminal or via the Qt Creator IDE_)
122+
123+
* Open the repo in VS Code
124+
* Click on the debug extension and select which example to execute
125+
![Debug dropdown window](resources/images/vscode_debug.jpg)
126+
127+
### Type III Examples: IntermediatePy and AdvancedPy (Python runtime with Python backend)
128+
129+
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.
130+
131+
#### Possible Issues
132+
133+
* If in Qt Creator some components are highlighted and marked as "Unknown component. (M300)", try resetting via "Tools > QML/JS > Reset Code Model".
134+
135+
### Type IV Examples: BasicC++ (QML backend)
136+
137+
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.
138+
139+
This example is currently used to create a WebAssembly application that can be run inside a web browser.

‎EasyApp/Gui/Html/plotly-2.18.0.min.js

-8
This file was deleted.

‎EasyApp/__init__.py

-1
This file was deleted.

‎LICENSE.md ‎LICENSE

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
BSD 3-Clause License
22

3-
Copyright (c) 2021-2022, European Spallation Source
3+
Copyright (c) 2024, EasyApp contributors (https://github.com/easyscience/EasyApp).
44
All rights reserved.
55

66
Redistribution and use in source and binary forms, with or without

‎README.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<img src="https://github.com/EasyScience/EasyApp/blob/examples/resources/images/ea_logo.svg?raw=true" height="65">
2+
3+
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.
4+
5+
* Website: https://app.easyscience.software
6+
* Source code: https://github.com/EasyScience/EasyApp
7+
* Bug reports: https://github.com/EasyScience/EasyApp/issues
8+
9+
EasyApp is currently being used as the basis for the graphical interface in the following projects:
10+
11+
* [EasyDiffraction](http://github.com/EasyScience/EasyDiffraction)
12+
* [EasyReflectometry](http://github.com/EasyScience/EasyReflectometry)
13+
* [EasyTexture](http://github.com/EasyScience/EasyTextureApp)
14+
15+
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:
16+
17+
* [BasicQml](https://github.com/EasyScience/EasyApp/tree/master/examples/BasicQml)
18+
* [BasicPy](https://github.com/EasyScience/EasyApp/tree/master/examples/BasicPy)
19+
* [BasicC++](https://github.com/EasyScience/EasyApp/tree/master/examples/BasicC++)
20+
* [IntermediatePy](https://github.com/EasyScience/EasyApp/tree/master/examples/IntermediatePy)
21+
* [AdvancedPy](https://github.com/EasyScience/EasyApp/tree/master/examples/AdvancedPy)
22+
23+
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.

‎docs/Developer/description.txt

Whitespace-only changes.

‎docs/UserManual/description.txt

Whitespace-only changes.

0 commit comments

Comments
 (0)