From 6d1177b36d4fc89012377d3dbe19867737b80c2e Mon Sep 17 00:00:00 2001 From: Christian Tismer Date: Mon, 27 Jan 2020 15:00:58 +0100 Subject: Add some qApp documentation Updated to the new simple builtin variable. Change-Id: I918ce7bc9aea6451439a8306d5bbd325c04e8136 Reviewed-by: Cristian Maureira-Fredes --- sources/pyside2/doc/considerations.rst | 52 +++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) (limited to 'sources/pyside2/doc') diff --git a/sources/pyside2/doc/considerations.rst b/sources/pyside2/doc/considerations.rst index c8d24d13d..f05d929b5 100644 --- a/sources/pyside2/doc/considerations.rst +++ b/sources/pyside2/doc/considerations.rst @@ -22,7 +22,7 @@ same hash. QString -~~~~~~~~ +~~~~~~~ Methods and functions that change the contents of a QString argument were modified to receive an immutable Python Unicode (or str) and return another Python Unicode/str as the modified string. @@ -83,3 +83,53 @@ its original Python object type. When a method expects a ``QVariant::Type`` the programmer can use a string (the type name) or the type itself. + + +qApp "macro" +~~~~~~~~~~~~ + +The C++ API of QtWidgets provides a macro called ``qApp`` that roughly expands to +``QtWidgets::QApplication->instance()``. + +In PySide, we tried to create a macro-like experience. +For that, the ``qApp`` variable was implemented as a normal variable +that lives in the builtins. +After importing ``PySide2``, you can immediately use ``qApp``. + +As a useful shortcut for the action "create an application if it was not created", we recommend:: + + qApp or QtWidgets.QApplication() + +or if you want to check if there is one, simply use the truth value:: + + if qApp: + # do something if an application was created + pass + +Comparing to ``None`` is also possible, but slightly over-specified. + + +Testing support ++++++++++++++++ + +For testing purposes, you can also get rid of the application by calling:: + + qApp.shutdown() + +As for 5.14.2, this is currently an experimental feature that is not fully tested. + + +Embedding status +++++++++++++++++ + +In embedded mode, application objects that are pre-created in C++ don't have a Python wrapper. +The ``qApp`` variable is created together with a wrapped application. +Therefore, ``qApp`` does not exist in that embedded mode. +Please note that you always can use ``QtWidgets.QApplication.instance()`` instead. + + +Abandoned Alternative ++++++++++++++++++++++ + +We also tried an alternative implementation with a ``qApp()`` function that was more *pythonic* +and problem free, but many people liked the ``qApp`` macro better for its brevity, so here it is. -- cgit v1.2.3