Integrate unofficial examples with screenshots

Author: mherrmann

README.md

@@ -1,2 +1,68 @@
-# examples
-Examples files for PyQt5
+# PyQt examples: Desktop GUIs based on PyQt5
+
+These PyQt examples teach you to create a desktop app with Python. Start with "Hello World" and work your way up to the official [demos](src/pyqt-official) that ship with PyQt.
+
+The screenshots below were taken on Ubuntu Linux. You can also use Windows or macOS.
+
+| <a href="src/01 PyQt QLabel"><img src="src/01 PyQt QLabel/pyqt-qlabel.png" alt="PyQt QLabel" width=100px></a> | <a href="src/02 PyQt Widgets"><img src="src/02 PyQt Widgets/pyqt-widgets.png" alt="PyQt widgets screenshot" width=200px></a> | <a href="src/03 QVBoxLayout PyQt5"><img src="src/03 QVBoxLayout PyQt5/qvboxlayout-pyqt5.png" alt="QVBoxLayout PyQt5" width=100px></a> | <a href="src/04 PyQt Signals and Slots"><img src="src/04 PyQt Signals and Slots/pyqt-signals-and-slots.jpg" alt="PyQt Signals and Slots" width=170px></a> | <a href="src/05 Qt Designer Python"><img src="src/05 Qt Designer Python/qt-designer-windows.png" alt="Qt Designer Python" width=190px></a> |
+| :--: | :--: | :--: | :--: | :--: |
+| <a href="src/01 PyQt QLabel">Hello World!</a> | <a href="src/02 PyQt Widgets">Common PyQt Widgets</a> | <a href="src/03 QVBoxLayout PyQt5">Layouts</a> | <a href="src/04 PyQt Signals and Slots">Signals and Slots</a> | <a href="src/04 Qt Designer Python">Qt Designer & Python</a> |
+
+| <a href="src/06 QML Python example"><img src="src/06 QML Python example/qml-python-example.png" alt="QML Python example" width=200px></a> | <a href="src/07 Qt Text Editor"><img src="src/07 Qt Text Editor/screenshots/qt-text-editor.png" alt="Qt Text Editor" width=180px></a> | <a href="src/08 PyQt5 exe"><img src="src/08 PyQt5 exe/pyqt5-exe.png" alt="PyQt5 exe" width=213px></a> | <a href="src/09 Qt dark theme"><img src="src/09 Qt dark theme/qt-dark-theme.png" alt="Qt dark theme" width=180px></a> |
+| :--: | :--: | :--: | :--: |
+| <a href="src/06 QML Python example">QML Python example</a> | <a href="src/07 Qt Text Editor">Qt Text Editor</a> | <a href="src/08 PyQt5 exe">Packaging & deployment</a> | <a href="src/09 Qt dark theme">Qt Dark Theme</a> |
+
+| <a href="src/10 QPainter Python example"><img src="src/10 QPainter Python example/qpainter-python-example.png" alt="QPainter Python example" width=200px></a> | <a href="src/11 PyQt Thread example"><img src="src/11 PyQt Thread example/pyqt-thread-example.png" alt="PyQt Thread example" width=175px></a> | <a href="src/12 QTreeView example in Python"><img src="src/12 QTreeView example in Python/qtreeview-example-in-python.png" alt="QTreeView example in Python" width=260px></a> | <a href="src/13 PyQt5 QListView"><img src="src/13 PyQt5 QListView/pyqt5-qlistview.png" alt="PyQt5 QListView" width=138px></a> |
+| :--: | :--: | :--: | :--: |
+| <a href="src/10 QPainter Python example">Action Shooter</a> | <a href="src/11 PyQt Thread example">Chat Client</a> | <a href="src/12 QTreeView example in Python">Tree Views</a> | <a href="src/13 PyQt5 QListView">Lists</a> |
+
+| <a href="src/14 QAbstractTableModel example"><img src="src/14 QAbstractTableModel example/qabstracttablemodel-example.png" alt="QAbstractTableModel example" height=120px></a> | <a href="src/15 PyQt database example"><img src="src/15 PyQt database example/pyqt-database-example.png" alt="QAbstractTableModel example" height=120px></a> |
+| :--: | :--: |
+| <a href="src/14 QAbstractTableModel example">Custom Tables</a> |  <a href="src/15 PyQt database example">PyQt database example</a> |
+
+## Running the examples
+
+Running the examples is really easy. The only thing you need is [Python 3](https://www.python.org/downloads/).
+
+First, download the [ZIP archive of this repository](https://github.com/pyqt/examples/archive/master.zip) and unpack it. Open a command prompt and use `cd` to navigate into the top-level directory of the archive.
+
+Create a virtual environment via the command:
+
+    python3 -m venv venv
+
+This creates the folder `venv/` in your current directory. It will contain the necessary libraries for running the examples.
+
+To activate the virtual environment, use the following command:
+
+```
+# On Windows:
+call venv\Scripts\actviate.bat
+# On Mac / Linux:
+source venv/bin/activate
+```
+
+Now execute the following to install the necessary dependencies:
+
+    pip install -Ur src/requirements.txt
+
+Once you have done this, use `cd` to navigate to the example you're interested in in the [`src/`](src) folder. For example:
+
+    cd "src/01 PyQt QLabel"
+
+You'll find a `.py` file there, typically `main.py`. You can run it with the command:
+
+    python main.py
+
+Please note that the virtual environment must still be active for this to work.
+
+## Using PySide2
+
+This repository uses PyQt5 to use Qt from Python. Another, alternative binding is PySide2 (also called "Qt for Python"). It is less mature than PyQt5 but has the advantage that you can use it for free in commercial projects.
+
+If you want to use PySide2 instead of PyQt5, simply replace all mentions of the latter by the former. For instance, in [`src/requirements.txt`](src/requirements.txt), replace `PyQt5` by `PySide2`. Similarly for any code examples: `from PyQt5.QtWidgets ...` becomes `from PySide2.QtWidgets ...` etc.
+
+Alternatively, if you don't want to commit to either of the two bindings at this stage, you can also use [Qt.py](https://github.com/mottosso/Qt.py). This is an abstraction over PySide2 and PyQt5. It loads whichever of the two bindings is available. To use it for the examples presented here, replace all mentions of `PyQt5` by just `Qt`.
+
+## License
+
+Except where otherwise indicated, the contents here are © me, Michael Herrmann. I'm happy for you to use the source code under the terms of the MIT license. The screenshots may be used under the terms of the [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/).

src/.gitignore

@@ -0,0 +1,105 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+*.qmlc

src/01 PyQt QLabel/README.md

@@ -0,0 +1,39 @@
+# PyQt QLabel
+
+This example shows how you can create a Hello World app using PyQt. It uses a [`QLabel`](https://doc.qt.io/qt-5/qlabel.html) to display a simple window:
+
+![PyQt QLabel screenshot](pyqt-qlabel.png)
+
+```
+from PyQt5.QtWidgets import *
+app = QApplication([])
+label = QLabel('Hello World!')
+label.show()
+app.exec_()
+```
+
+For instructions how you can run this code, please see the [top-level README](https://github.com/1mh/pyqt-examples#running-the-examples).
+
+The code works as follows: First, we import the necessary PyQt classes via the statement:
+
+    from PyQt5.QtWidgets import *
+
+Next, we create a [`QApplication`](https://doc.qt.io/Qt-5/qapplication.html). This is required in every PyQt app. In a sense, it initializes PyQt:
+
+    app = QApplication([])
+
+Then, we create the label with the text we want:
+
+    label = QLabel('Hello World!')
+
+By calling `.show()` on a [widget](../02%20PyQt%20Widgets), we can spawn a window that displays it:
+
+    label.show()
+
+Finally, we hand control over to Qt:
+
+    app.exec_()
+
+This too is required in every Qt application. It gives Qt a chance to run and process user input, such as for instance when the user clicks the "Window close" button.
+
+And that's it! Congratulations on your first PyQt app :-)

src/01 PyQt QLabel/main.py

@@ -0,0 +1,5 @@
+from PyQt5.QtWidgets import *
+app = QApplication([])
+label = QLabel('Hello World!')
+label.show()
+app.exec_()

src/01 PyQt QLabel/pyqt-qlabel.png

@@ -0,0 +1,21 @@
+# PyQt Widgets
+
+A *widget* is a GUI element: A button, a text field, ... The sample application in this directory shows the most common PyQt widgets:
+
+![PyQt widgets screenshot](pyqt-widgets.png)
+
+If you know HTML: Widgets are a little like HTML elements. They can be nested, and have a different appearance and behavior depending on their type. (Eg. a link `<a>` looks and behaves differently from an image `<img>`.)
+
+Some of the widgets you can see in this screenshot are:
+
+ * [QLabel](https://doc.qt.io/qt-5/qlabel.html)
+ * [QComboBox](https://doc.qt.io/qt-5/qcombobox.html)
+ * [QCheckBox](https://doc.qt.io/qt-5/qcheckbox.html)
+ * [QRadioButton](https://doc.qt.io/qt-5/qradiobutton.html)
+ * [QPushButton](https://doc.qt.io/qt-5/qpushbutton.html)
+ * [QTableWidget](https://doc.qt.io/qt-5/qtablewidget.html)
+ * [QLineEdit](https://doc.qt.io/qt-5/qlineedit.html)
+ * [QSlider](https://doc.qt.io/qt-5/qslider.html)
+ * [QProgressBar](https://doc.qt.io/qt-5/qprogressbar.html)
+
+The source code for this application is in [`main.py`](main.py). For instructions how to run it, please see [here](https://github.com/1mh/pyqt-examples#running-the-examples). Don't worry if you don't yet fully understand the source code. The main purpose of this example is to give you a feel for what a widget is, and which ones are available. The next examples give you a more gradual route to more advanced PyQt topics.