Skip to content

Commit

Permalink
Update EXAMPLES.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@AndrewSazonov
AndrewSazonov committed Aug 19, 2024
1 parent 3af9489 commit c6c7e97
Showing 1 changed file with 67 additions and 39 deletions.
106 changes: 67 additions & 39 deletions EXAMPLES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,27 +11,42 @@ Different types of examples are provided. All examples have a frontend implement
| BasicC++ | IV | QML | Mock QML | need to be compiled |


## Python environment and IDE
## Setting up Python and IDE

### Python environment
* Install the Qt `PySide6` module in the desired python environment
***macOS and Linux***

```sh
$ python3.11 -m venv .venv # create new python environment '.venv'
$ source .venv/bin/activate # activate '.venv'
$ pip install PySide6 # install Qt for Python
* Create and activate a python environment (_optional_)

***macOS and Linux***

```
python3.11 -m venv .venv
source .venv/bin/activate
```

***Windows***
***Windows***

```sh
$ python3.11 -m venv .venv # create new python environment '.venv'
$ .venv\Scripts\activate # activate '.venv'
$ pip install PySide6 # install Qt for Python
```
python3.11 -m venv .venv
.venv\Scripts\activate
```

* Upgrade the PIP - package installer for Python (_optional_)

```
pip install --upgrade pip
```

* Install the Qt for Python `PySide6` package via PIP

```
pip install PySide6
```

### Integrated development environment (IDE)

#### Qt Creator

### QT Creator
* 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
Expand All @@ -44,39 +59,45 @@ Different types of examples are provided. All examples have a frontend implement
* [ ] Developer and Designer Tools
* [x] Qt Creator x.y.z

### VSCode
* Download an install VSCode
#### VS Code (_alternative to Qt Creator_)

* Download an install VS Code
* Add the python extension
* Rename the folder `vscode` to `.vscode`. The `launch.json` file will then be read by VSCode
* 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)

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`, whcih can be displayed using Qt `qml` viewer.
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.

#### Qt Creator IDE (QML Runtime)
* Run Qt Creator
* Open the qml project file `*.qmlproject` from the example folder from `src/BasicQml.qmlproject`
* Click Run (Green play button)
#### Run using the QML Runtime

##### Run from the terminal

#### Run from the terminal (QML Runtime)
* Go to the example folder, e.g.,

```sh
$ cd examples/BasicQml/src/BasicQml
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
~/Qt/6.x.y/macos/bin/qml -I . -I ../../../.. main.qml
```

##### Run via the Qt Creator IDE (_alternative to run from the terminal_)

* 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

* 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).
Expand All @@ -87,30 +108,35 @@ This example is located in `examples/BasicQml` and the source code is in the sub

This example is located in `examples/BasicMinimalPy` with the source code in `src/BasicMinimalPy`. 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:

#### QtCreator IDE (Python Runtime)
* Run Qt Creator
* Open the python project file `*.pyproject` from the example folder from `examples/BasicMinimalPy/src/BasicMinimalPy.pyproject`
* Select the desired python environment with the Qt `PySide6` module installed
* Click Run (Green play button)
#### Run using the Python interpreter

#### VSCode IDE (Python Runtime)
* Open the repo in VSCode
* Click on the debug extension and select which example to execute
![Debug dropdown window](.\resources\images\vscode_debug.jpg)
##### Run from the terminal

#### Run from the terminal (Python Runtime)
* Go to the example folder, e.g.,

```sh
$ cd examples/BasicMinimalPy/src/BasicMinimalPy
```
* Run using Python (provided that the required python environment is activated)
* Run using Python (provided that the required python environment is activated as explained above)

```sh
$ python3 main.py
$ python main.py
```

### Type III Examples: BasicPy and IntermediatePy (Python runtime with Py backend)
#### 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/BasicMinimalPy/src/BasicMinimalPy.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: BasicPy and IntermediatePy (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 `Logic/Py/backend_proxy.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 frontend then acceses the backend by calling methods exposed by the proxy object in the `Py` folder.

Expand All @@ -120,4 +146,6 @@ These examples demonstrate how to use a Python runtime to execute the QML fronte

### Type IV Examples: BasicC++

These examples can be run after compilation into an executable program. They only have 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 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.

0 comments on commit c6c7e97

Please sign in to comment.